feat: event record with attribute and limit

Author: zhu-xiaowei

Package.swift

@@ -10,18 +10,18 @@ let package = Package(
     products: [
         .library(
             name: "Clickstream",
-            targets: ["Clickstream"]),
+            targets: ["Clickstream"])
     ],
     dependencies: [
-        .package(url: "https://github.com/aws-amplify/amplify-swift.git", exact: "2.4.0"),
+        .package(url: "https://github.com/aws-amplify/amplify-swift.git", exact: "2.4.0")
     ],
     targets: [
         .target(
             name: "Clickstream",
             dependencies: [
-                .product(name: "AWSPluginsCore", package: "amplify-swift"),
+                .product(name: "AWSPluginsCore", package: "amplify-swift")
             ]),
         .testTarget(
             name: "ClickstreamTests",
-            dependencies: ["Clickstream"]),
+            dependencies: ["Clickstream"])
     ])

Sources/Clickstream/AWSClickstreamPlugin+ClientBehavior.swift

@@ -9,17 +9,79 @@ import Amplify
 import Foundation
 
 public extension AWSClickstreamPlugin {
-    func identifyUser(userId: String, userProfile: AnalyticsUserProfile?) {}
+    func identifyUser(userId: String, userProfile: AnalyticsUserProfile?) {
+        Task {
+            if userId == Event.User.USER_ID_NIL {
+                await analyticsClient.removeUserAttribute(forKey: userId)
+            } else if userId != Event.User.USER_ID_EMPTY {
+                await analyticsClient.addUserAttribute(userId, forKey: Event.ReservedAttribute.USER_ID)
+            }
+        }
+        userProfile?.properties?.forEach { key, value in
+            Task {
+                await analyticsClient.addUserAttribute(value, forKey: key)
+            }
+        }
+    }
 
-    func record(event: AnalyticsEvent) {}
+    func record(event: AnalyticsEvent) {
+        if !isEnabled {
+            log.warn("Cannot record events. Clickstream is disabled")
+            return
+        }
+        let clickstreamEvent = analyticsClient.createEvent(withEventType: event.name)
+        if let properties = event.properties {
+            clickstreamEvent.addProperties(properties)
+        }
 
-    func record(eventWithName eventName: String) {}
+        Task {
+            do {
+                try await analyticsClient.record(clickstreamEvent)
+            } catch {
+                log.error("Record event error:\(error)")
+            }
+        }
+    }
 
-    func registerGlobalProperties(_ properties: AnalyticsProperties) {}
+    func record(eventWithName eventName: String) {
+        let event = BasicAnalyticsEvent(name: eventName)
+        record(event: event)
+    }
 
-    func unregisterGlobalProperties(_ keys: Set<String>?) {}
+    func registerGlobalProperties(_ properties: AnalyticsProperties) {
+        properties.forEach { key, value in
+            Task {
+                await analyticsClient.addGlobalAttribute(value, forKey: key)
+            }
+        }
+    }
 
-    func flushEvents() {}
+    func unregisterGlobalProperties(_ keys: Set<String>?) {
+        keys?.forEach { key in
+            Task {
+                await analyticsClient.removeGlobalAttribute(forKey: key)
+            }
+        }
+    }
+
+    func flushEvents() {
+        if !isEnabled {
+            log.warn("Cannot flushEvents. Clickstream is disabled")
+            return
+        }
+        // Do not attempt to submit events if we detect the device is offline, as it's gonna fail anyway
+        guard networkMonitor.isOnline else {
+            log.error("Device is offline, skipping submitting events to Clickstream server")
+            return
+        }
+        Task {
+            try await analyticsClient.submitEvents()
+        }
+    }
+
+    func getEscapeHatch() -> ClickstreamContextConfiguration {
+        clickstream.configuration
+    }
 
     func enable() {
         isEnabled = true

Sources/Clickstream/AWSClickstreamPlugin+Configure.swift

@@ -7,6 +7,7 @@
 
 import Amplify
 import Foundation
+import Network
 
 public extension AWSClickstreamPlugin {
     /// called when sdk init.
@@ -22,5 +23,68 @@ public extension AWSClickstreamPlugin {
     }
 
     /// Configure AWSClickstreamPlugin programatically using AWSClickstreamConfiguration
-    func configure(using configuration: AWSClickstreamConfiguration) throws {}
+    func configure(using configuration: AWSClickstreamConfiguration) throws {
+        let contextConfiguration = ClickstreamContextConfiguration(appId: configuration.appId,
+                                                                   endpoint: configuration.endpoint,
+                                                                   sendEventsInterval: configuration.sendEventsInterval,
+                                                                   isTrackAppExceptionEvents: configuration.isTrackAppExceptionEvents,
+                                                                   isCompressEvents: configuration.isCompressEvents)
+        let clickstream = try ClickstreamContext(with: contextConfiguration)
+
+        let sessionClient = SessionClient(configuration: .init(uniqueDeviceId: clickstream.uniqueId,
+                                                               sessionBackgroundTimeout: TimeInterval(10)),
+                                          userDefaults: clickstream.storage.userDefaults)
+        clickstream.sessionClient = sessionClient
+        let sessionProvider: () -> Session = { [weak sessionClient] in
+            guard let sessionClient else {
+                fatalError("SessionClient was deallocated")
+            }
+            return sessionClient.currentSession
+        }
+        let eventRecorder = try EventRecorder(clickstream: clickstream)
+        analyticsClient = try AnalyticsClient(clickstream: clickstream,
+                                              eventRecorder: eventRecorder,
+                                              sessionProvider: sessionProvider)
+        clickstream.analyticsClient = analyticsClient
+        sessionClient.analyticsClient = analyticsClient
+        let networkMonitor = NWPathMonitor()
+        clickstream.networkMonitor = networkMonitor
+
+        var autoFlushEventsTimer: DispatchSourceTimer?
+        if configuration.sendEventsInterval != 0 {
+            let timeInterval = TimeInterval(configuration.sendEventsInterval / 1000)
+            autoFlushEventsTimer = RepeatingTimer.createRepeatingTimer(
+                timeInterval: timeInterval,
+                eventHandler: { [weak self] in
+                    self?.log.debug("AutoFlushTimer triggered, flushing events")
+                    self?.flushEvents()
+                }
+            )
+        }
+
+        configure(clickstream: clickstream,
+                  autoFlushEventsTimer: autoFlushEventsTimer,
+                  networkMonitor: networkMonitor)
+        sessionClient.startSession()
+        log.debug("init the sdk success")
+    }
+
+    // MARK: Internal
+
+    /// Internal configure method to set the properties of the plugin
+    internal func configure(clickstream: ClickstreamContext,
+                            autoFlushEventsTimer: DispatchSourceTimer?,
+                            networkMonitor: NetworkMonitor)
+    {
+        self.clickstream = clickstream
+        isEnabled = true
+        self.autoFlushEventsTimer = autoFlushEventsTimer
+        self.autoFlushEventsTimer?.resume()
+        self.networkMonitor = networkMonitor
+        self.networkMonitor.startMonitoring(
+            using: DispatchQueue(
+                label: "com.amazonaws.solution.clickstream.AnalyticsPlugin.NetworkMonitor"
+            )
+        )
+    }
 }

Sources/Clickstream/AWSClickstreamPlugin+DefaultLogger.swift

@@ -6,6 +6,5 @@
 //
 
 import Amplify
-import Foundation
 
 extension AWSClickstreamPlugin: DefaultLogger {}

Sources/Clickstream/AWSClickstreamPlugin+Reset.swift

@@ -5,10 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
-import Foundation
-
 public extension AWSClickstreamPlugin {
-    func reset() async {
+    func reset() {
+        if clickstream != nil {
+            clickstream = nil
+        }
+
         if autoFlushEventsTimer != nil {
             autoFlushEventsTimer?.setEventHandler {}
             autoFlushEventsTimer?.cancel()

Sources/Clickstream/AWSClickstreamPlugin.swift

@@ -6,24 +6,28 @@
 //
 
 import Amplify
-import AWSPluginsCore
 import Foundation
 
 public final class AWSClickstreamPlugin: AnalyticsCategoryPlugin {
+    var clickstream: ClickstreamContext!
+
     /// Automatically flushes the events that have been recorded on an interval
     var autoFlushEventsTimer: DispatchSourceTimer?
-    
+
     /// An observer to monitor connectivity changes
     var networkMonitor: NetworkMonitor!
-    
+
     /// Specifies whether the plugin is enabled
     var isEnabled: Bool!
-    
+
+    /// ClickstreamClient for evnet handle
+    var analyticsClient: AnalyticsClientBehaviour!
+
     /// The configuration file plugin key of clickstream plugin
     public var key: PluginKey {
         "awsClickstreamPlugin"
     }
-    
+
     /// Instantiates an instance of the AWSClickstreamPlugin
     public init() {}
 }

Sources/Clickstream/ClickstreamAnalytics.swift

@@ -13,4 +13,59 @@ public enum ClickstreamAnalytics {
         try Amplify.add(plugin: AWSClickstreamPlugin())
         try Amplify.configure()
     }
+
+    /// Use this method to record Event.
+    /// - Parameter event: ClickstreamEvent to record
+    public static func recordEvent(event: AnalyticsEvent) {
+        Amplify.Analytics.record(event: event)
+    }
+
+    /// Use this method to record Event.
+    /// - Parameter eventName: the event name
+    public static func recordEvent(eventName: String) {
+        Amplify.Analytics.record(eventWithName: eventName)
+    }
+
+    /// Use this method to send events immediately.
+    public static func flushEvents() {
+        Amplify.Analytics.flushEvents()
+    }
+
+    /// Add global attributes
+    /// - Parameter attributes: the global attributes to add
+    public static func addGlobalAttributes(attributes: ClickstreamAttribute) {
+        Amplify.Analytics.registerGlobalProperties(attributes)
+    }
+
+    /// Delete global attributes
+    /// - Parameter attributes: the global attributes to delete
+    public static func deleteGlobalAttributes(attributes: String...) {
+        Amplify.Analytics.unregisterGlobalProperties(attributes)
+    }
+
+    /// Add user attributes
+    /// - Parameter attributes: the user attributes to add
+    public static func addUserAttributes(userAttributes: ClickstreamUserAttribute) {
+        let userId: String = userAttributes.userId ?? Event.User.USER_ID_EMPTY
+        let userProfile = AnalyticsUserProfile(location: nil, properties: userAttributes.attribute)
+        Amplify.Analytics.identifyUser(userId: userId,
+                                       userProfile: userProfile)
+    }
+
+    /// Set user id for login and logout
+    /// - Parameter userId: current userId, nil for logout
+    public static func setUserId(userId: String?) {
+        if userId == nil {
+            Amplify.Analytics.identifyUser(userId: Event.User.USER_ID_NIL)
+        } else {
+            Amplify.Analytics.identifyUser(userId: userId!)
+        }
+    }
+
+    /// Get clickstream configuration, please config it after initialize.
+    /// - Returns: ClickstreamContextConfiguration: current userId, nil for logout
+    public static func getClickStreamConfiguration() throws -> ClickstreamContextConfiguration? {
+        let plugin = try Amplify.Analytics.getPlugin(for: "awsClickstreamPlugin")
+        return (plugin as? AWSClickstreamPlugin)?.getEscapeHatch()
+    }
 }

Sources/Clickstream/ClickstreamAttribute.swift

@@ -0,0 +1,21 @@
+//
+//  File.swift
+//
+//
+//  Created by Zhu, Xiaowei on 2023/3/4.
+//
+
+import Amplify
+
+public typealias ClickstreamAttribute = AnalyticsProperties
+public typealias BaseClickstreamEvent = BasicAnalyticsEvent
+public typealias AttributeValue = AnalyticsPropertyValue
+
+public struct ClickstreamUserAttribute {
+    public var userId: String?
+    public var attribute: ClickstreamAttribute?
+    public init(userId: String?, attribute: ClickstreamAttribute?) {
+        self.userId = userId
+        self.attribute = attribute
+    }
+}

Sources/Clickstream/Configuration/AWSClickstreamPluginConfiguration.swift

@@ -6,14 +6,12 @@
 //
 
 import Amplify
-import AWSClientRuntime
-import Foundation
 
 public struct AWSClickstreamConfiguration {
     static let appIdKey = "appId"
     static let endpointKey = "endpoint"
     static let sendEventsIntervalKey = "autoFlushEventsInterval"
-    static let trackAppExceptionKey = "isTrackAppExceptionEvents"
+    static let isTrackAppExceptionKey = "isTrackAppExceptionEvents"
     static let isCompressEventsKey = "isCompressEvents"
 
     static let defaultSendEventsInterval = 10000
@@ -133,7 +131,7 @@ public struct AWSClickstreamConfiguration {
     }
 
     private static func getIsTrackAppExceptionEvents(_ configuration: [String: JSONValue]) throws -> Bool {
-        guard let isTrackAppException = configuration[trackAppExceptionKey] else {
+        guard let isTrackAppException = configuration[isTrackAppExceptionKey] else {
             return AWSClickstreamConfiguration.defaulTrackAppException
         }