Add eventID so that events can be timed independently of the event name.

Author: christian-riboldi

Sources/MixpanelInstance.swift

@@ -37,8 +37,8 @@ public protocol MixpanelDelegate: AnyObject {
 
 public typealias Properties = [String: MixpanelType]
 typealias InternalProperties = [String: Any]
-typealias EventID = String
-typealias TimedEvents = [EventID: TimeInterval]
+typealias TimedEventID = String
+typealias TimedEvents = [TimedEventID: TimeInterval]
 typealias Queue = [InternalProperties]
 
 protocol AppLifecycle {
@@ -1004,6 +1004,7 @@ extension MixpanelInstance {
 }
 
 extension MixpanelInstance {
+    
     // MARK: - Track
 
     /**
@@ -1019,13 +1020,30 @@ extension MixpanelInstance {
      - parameter properties: properties dictionary
      */
     public func track(event: String?, properties: Properties? = nil) {
+        track(event: event, withID: nil, properties: properties)
+    }
+    
+    /**
+     Tracks an event with properties.
+     Properties are optional and can be added only if needed.
+     
+     Properties will allow you to segment your events in your Mixpanel reports.
+     Property keys must be String objects and the supported value types need to conform to MixpanelType.
+     MixpanelType can be either String, Int, UInt, Double, Float, Bool, [MixpanelType], [String: MixpanelType], Date, URL, or NSNull.
+     If the event is being timed, the timer will stop and be added as a property.
+     
+     - parameter event:      event name
+     - parameter withID:     eventID used to link timed events previously timed using `time(eventID)`
+     - parameter properties: properties dictionary
+     */
+    public func track(event: String?, withID eventID: String?, properties: Properties? = nil) {
         if hasOptedOutTracking() {
             return
         }
 
         let epochInterval = Date().timeIntervalSince1970
 
-        trackingQueue.async { [weak self, event, properties, epochInterval] in
+        trackingQueue.async { [weak self, event, eventID, properties, epochInterval] in
             guard let self = self else {
                 return
             }
@@ -1044,6 +1062,7 @@ extension MixpanelInstance {
                                                          alias: nil,
                                                          hadPersistedDistinctId: self.hadPersistedDistinctId)
             let timedEventsSnapshot = self.trackInstance.track(event: event,
+                                                               eventID: eventID,
                                                                properties: properties,
                                                                timedEvents: shadowTimedEvents,
                                                                superProperties: shadowSuperProperties,
@@ -1172,10 +1191,36 @@ extension MixpanelInstance {
 
      */
     public func time(event: String) {
+        time(eventID: event)
+    }
+    
+    /**
+     Starts a timer that will be stopped and added as a property when a
+     corresponding event with the identidal eventID is tracked.
+     
+     This method is intended to be used in advance of events that have
+     a duration. For example, if a developer were to track an "Image Upload" event
+     she might want to also know how long the upload took. Calling this method
+     before the upload code would implicitly cause the `track`
+     call to record its duration.
+     
+     - precondition:
+     // begin timing the image upload:
+     mixpanelInstance.time(eventID:"some-unique-id")
+     // upload the image:
+     self.uploadImageWithSuccessHandler() { _ in
+     // track the event
+     mixpanelInstance.track("Image Upload", withID: "some-unique-id")
+     }
+     
+     - parameter eventID: the id of the event to be timed
+     
+     */
+    public func time(eventID: String) {
         let startTime = Date().timeIntervalSince1970
-        trackingQueue.async { [weak self, startTime, event] in
+        trackingQueue.async { [weak self, startTime, eventID] in
             guard let self = self else { return }
-            let timedEvents = self.trackInstance.time(event: event, timedEvents: self.timedEvents, startTime: startTime)
+            let timedEvents = self.trackInstance.time(eventID: eventID, timedEvents: self.timedEvents, startTime: startTime)
             self.readWriteLock.write {
                 self.timedEvents = timedEvents
             }
@@ -1189,12 +1234,21 @@ extension MixpanelInstance {
      - parameter event: the name of the event to be tracked that was passed to time(event:)
      */
     public func eventElapsedTime(event: String) -> Double {
+        eventElapsedTime(eventID: event)
+    }
+    
+    /**
+     Retrieves the time elapsed for the event given it's ID since time(eventID:) was called.
+     
+     - parameter event: the id of the event to be tracked that was passed to time(eventID:)
+     */
+    public func eventElapsedTime(eventID: String) -> Double {
         var timedEvents = TimedEvents()
         self.readWriteLock.read {
             timedEvents = self.timedEvents
         }
 
-        if let startTime = timedEvents[event] {
+        if let startTime = timedEvents[eventID] {
             return Date().timeIntervalSince1970 - startTime
         }
         return 0
@@ -1219,10 +1273,19 @@ extension MixpanelInstance {
      - parameter event: the name of the event to clear the timer for
      */
     public func clearTimedEvent(event: String) {
-        trackingQueue.async { [weak self, event] in
+        clearTimedEvent(eventId: event)
+    }
+    
+    /**
+     Clears the event timer for the provided eventID.
+     
+     - parameter event: the id of the event to clear the timer for
+     */
+    public func clearTimedEvent(eventId: String) {
+        trackingQueue.async { [weak self, eventId] in
             guard let self = self else { return }
 
-            let updatedTimedEvents = self.trackInstance.clearTimedEvent(event: event, timedEvents: self.timedEvents)
+            let updatedTimedEvents = self.trackInstance.clearTimedEvent(eventId: eventId, timedEvents: self.timedEvents)
             MixpanelPersistence.saveTimedEvents(timedEvents: updatedTimedEvents, instanceName: self.name)
         }
     }

Sources/Track.swift

@@ -32,29 +32,30 @@ class Track {
     }
 
     func track(event: String?,
+               eventID: TimedEventID?,
                properties: Properties? = nil,
                timedEvents: TimedEvents,
                superProperties: InternalProperties,
                mixpanelIdentity: MixpanelIdentity,
                epochInterval: Double) -> TimedEvents {
-        var ev = "mp_event"
-        if let event = event {
-            ev = event
+        var eventName = "mp_event"
+        if let event {
+            eventName = event
         } else {
             Logger.info(message: "mixpanel track called with empty event parameter. using 'mp_event'")
         }
-        if !(mixpanelInstance?.trackAutomaticEventsEnabled ?? false) && ev.hasPrefix("$ae_") {
+        if !(mixpanelInstance?.trackAutomaticEventsEnabled ?? false) && eventName.hasPrefix("$ae_") {
             return timedEvents
         }
-        let eventID = ev
+        let timedEventID = eventID ?? eventName
         assertPropertyTypes(properties)
         #if DEBUG
-        if !ev.hasPrefix("$") {
+        if !eventName.hasPrefix("$") {
             UserDefaults.standard.set(true, forKey: InternalKeys.mpDebugTrackedKey)
         }
         #endif
         let epochMilliseconds = round(epochInterval * 1000)
-        let eventStartTime = timedEvents[eventID]
+        let eventStartTime = timedEvents[timedEventID]
         var p = InternalProperties()
         AutomaticProperties.automaticPropertiesLock.read {
             p += AutomaticProperties.properties
@@ -63,7 +64,7 @@ class Track {
         p["time"] = epochMilliseconds
         var shadowTimedEvents = timedEvents
         if let eventStartTime = eventStartTime {
-            shadowTimedEvents.removeValue(forKey: eventID)
+            shadowTimedEvents.removeValue(forKey: timedEventID)
             p["$duration"] = Double(String(format: "%.3f", epochInterval - eventStartTime))
         }
         p["distinct_id"] = mixpanelIdentity.distinctID
@@ -82,7 +83,7 @@ class Track {
             p += properties
         }
 
-        var trackEvent: InternalProperties = ["event": ev, "properties": p]
+        var trackEvent: InternalProperties = ["event": eventName, "properties": p]
         metadata.toDict().forEach { (k, v) in trackEvent[k] = v }
 
         self.mixpanelPersistence.saveEntity(trackEvent, type: .events)
@@ -140,16 +141,16 @@ class Track {
         update(&superProperties)
     }
 
-    func time(event: String?, timedEvents: TimedEvents, startTime: Double) -> TimedEvents {
+    func time(eventID: TimedEventID, timedEvents: TimedEvents, startTime: TimeInterval) -> TimedEvents {
         if mixpanelInstance?.hasOptedOutTracking() ?? false {
             return timedEvents
         }
         var updatedTimedEvents = timedEvents
-        guard let event = event, !event.isEmpty else {
+        guard !eventID.isEmpty else {
             Logger.error(message: "mixpanel cannot time an empty event")
             return updatedTimedEvents
         }
-        updatedTimedEvents[event] = startTime
+        updatedTimedEvents[eventID] = startTime
         return updatedTimedEvents
     }
 
@@ -159,13 +160,13 @@ class Track {
         return updatedTimedEvents
     }
 
-    func clearTimedEvent(event: String?, timedEvents: TimedEvents) -> TimedEvents {
+    func clearTimedEvent(eventId: TimedEventID, timedEvents: TimedEvents) -> TimedEvents {
         var updatedTimedEvents = timedEvents
-        guard let event = event, !event.isEmpty else {
+        guard !eventId.isEmpty else {
             Logger.error(message: "mixpanel cannot clear an empty timed event")
             return updatedTimedEvents
         }
-        updatedTimedEvents.removeValue(forKey: event)
+        updatedTimedEvents.removeValue(forKey: eventId)
         return updatedTimedEvents
     }
 }