feat(autocapture): auto capture element interactions

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Next
 
+- add autocapture support for UIKit ([#224](https://github.com/PostHog/posthog-ios/pull/224))
+
 ## 3.13.1 - 2024-10-16
 
 - add optional distinctId parameter to capture methods ([#216](https://github.com/PostHog/posthog-ios/pull/216))

PostHog.xcodeproj/project.pbxproj

@@ -119,6 +119,10 @@
 		69F5181A2BAC81FC00F52C14 /* UITextInputTraits+Util.swift in Sources */ = {isa = PBXBuildFile; fileRef = 69F518192BAC81FC00F52C14 /* UITextInputTraits+Util.swift */; };
 		69F518382BB2BA0100F52C14 /* PostHogSwizzler.swift in Sources */ = {isa = PBXBuildFile; fileRef = 69F518372BB2BA0100F52C14 /* PostHogSwizzler.swift */; };
 		69F5183A2BB2BA8300F52C14 /* UIApplicationTracker.swift in Sources */ = {isa = PBXBuildFile; fileRef = 69F518392BB2BA8300F52C14 /* UIApplicationTracker.swift */; };
+		DA26419C2CC0499300CB427B /* PostHogAutocaptureIntegration.swift in Sources */ = {isa = PBXBuildFile; fileRef = DA26419A2CC0499300CB427B /* PostHogAutocaptureIntegration.swift */; };
+		DAC699D62CC790D9000D1D6B /* AutocaptureEventProcessing.swift in Sources */ = {isa = PBXBuildFile; fileRef = DAC699D52CC790D9000D1D6B /* AutocaptureEventProcessing.swift */; };
+		DAC699E52CC8EF57000D1D6B /* PostHogAutoCaptureConfig.swift in Sources */ = {isa = PBXBuildFile; fileRef = DAC699E42CC8EF57000D1D6B /* PostHogAutoCaptureConfig.swift */; };
+		DAC699EC2CCA73E5000D1D6B /* ForwardingPickerViewDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = DAC699EB2CCA73E5000D1D6B /* ForwardingPickerViewDelegate.swift */; };
 		DAD5DD0C2CB6DEF30087387B /* PostHogMaskViewModifier.swift in Sources */ = {isa = PBXBuildFile; fileRef = DAD5DD072CB6DEE70087387B /* PostHogMaskViewModifier.swift */; };
 /* End PBXBuildFile section */
 
@@ -200,6 +204,13 @@
 			remoteGlobalIDString = 3AC745B4296D6FE60025C109;
 			remoteInfo = PostHog;
 		};
+		DA8D37282CBEAC03005EBD27 /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = DA8D37242CBEAC02005EBD27 /* PostHogExampleAutocapture.xcodeproj */;
+			proxyType = 2;
+			remoteGlobalIDString = 228DB9F318BC53F1002BA12A;
+			remoteInfo = PostHogExampleAutocapture;
+		};
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -376,6 +387,11 @@
 		69F518192BAC81FC00F52C14 /* UITextInputTraits+Util.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "UITextInputTraits+Util.swift"; sourceTree = "<group>"; };
 		69F518372BB2BA0100F52C14 /* PostHogSwizzler.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogSwizzler.swift; sourceTree = "<group>"; };
 		69F518392BB2BA8300F52C14 /* UIApplicationTracker.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UIApplicationTracker.swift; sourceTree = "<group>"; };
+		DA26419A2CC0499300CB427B /* PostHogAutocaptureIntegration.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogAutocaptureIntegration.swift; sourceTree = "<group>"; };
+		DA8D37242CBEAC02005EBD27 /* PostHogExampleAutocapture.xcodeproj */ = {isa = PBXFileReference; lastKnownFileType = "wrapper.pb-project"; name = PostHogExampleAutocapture.xcodeproj; path = PostHogExampleAutocapture/PostHogExampleAutocapture.xcodeproj; sourceTree = "<group>"; };
+		DAC699D52CC790D9000D1D6B /* AutocaptureEventProcessing.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AutocaptureEventProcessing.swift; sourceTree = "<group>"; };
+		DAC699E42CC8EF57000D1D6B /* PostHogAutoCaptureConfig.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogAutoCaptureConfig.swift; sourceTree = "<group>"; };
+		DAC699EB2CCA73E5000D1D6B /* ForwardingPickerViewDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ForwardingPickerViewDelegate.swift; sourceTree = "<group>"; };
 		DAD5DD072CB6DEE70087387B /* PostHogMaskViewModifier.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogMaskViewModifier.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
@@ -503,6 +519,7 @@
 		3AC745AB296D6FE60025C109 = {
 			isa = PBXGroup;
 			children = (
+				DA8D37242CBEAC02005EBD27 /* PostHogExampleAutocapture.xcodeproj */,
 				690FF1732AF3CE8A00A0B06B /* PostHogExampleWatchOS.xcodeproj */,
 				690FF0532AE7DB3700A0B06B /* PostHogExampleWithSPM.xcodeproj */,
 				690FF02F2AE7C5BA00A0B06B /* PostHogExampleWithPods.xcodeproj */,
@@ -536,6 +553,7 @@
 		3AC745B7296D6FE60025C109 /* PostHog */ = {
 			isa = PBXGroup;
 			children = (
+				DA26419B2CC0499300CB427B /* Autocapture */,
 				69EE82B82BA9C4DA00EB9542 /* Replay */,
 				69BA38E62B893F2200AA69D6 /* Resources */,
 				69779BED2AE6B29E00D7A48E /* Models */,
@@ -733,6 +751,25 @@
 			path = PostHogExampleStoryboard;
 			sourceTree = "<group>";
 		};
+		DA26419B2CC0499300CB427B /* Autocapture */ = {
+			isa = PBXGroup;
+			children = (
+				DAC699EB2CCA73E5000D1D6B /* ForwardingPickerViewDelegate.swift */,
+				DAC699E42CC8EF57000D1D6B /* PostHogAutoCaptureConfig.swift */,
+				DAC699D52CC790D9000D1D6B /* AutocaptureEventProcessing.swift */,
+				DA26419A2CC0499300CB427B /* PostHogAutocaptureIntegration.swift */,
+			);
+			path = Autocapture;
+			sourceTree = "<group>";
+		};
+		DA8D37252CBEAC02005EBD27 /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				DA8D37292CBEAC03005EBD27 /* PostHogExampleAutocapture.app */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
 /* End PBXGroup section */
 
 /* Begin PBXHeadersBuildPhase section */
@@ -939,6 +976,10 @@
 			productRefGroup = 3AC745B6296D6FE60025C109 /* Products */;
 			projectDirPath = "";
 			projectReferences = (
+				{
+					ProductGroup = DA8D37252CBEAC02005EBD27 /* Products */;
+					ProjectRef = DA8D37242CBEAC02005EBD27 /* PostHogExampleAutocapture.xcodeproj */;
+				},
 				{
 					ProductGroup = 690FF1742AF3CE8A00A0B06B /* Products */;
 					ProjectRef = 690FF1732AF3CE8A00A0B06B /* PostHogExampleWatchOS.xcodeproj */;
@@ -994,6 +1035,13 @@
 			remoteRef = 690FF17A2AF3CE8B00A0B06B /* PBXContainerItemProxy */;
 			sourceTree = BUILT_PRODUCTS_DIR;
 		};
+		DA8D37292CBEAC03005EBD27 /* PostHogExampleAutocapture.app */ = {
+			isa = PBXReferenceProxy;
+			fileType = wrapper.application;
+			path = PostHogExampleAutocapture.app;
+			remoteRef = DA8D37282CBEAC03005EBD27 /* PBXContainerItemProxy */;
+			sourceTree = BUILT_PRODUCTS_DIR;
+		};
 /* End PBXReferenceProxy section */
 
 /* Begin PBXResourcesBuildPhase section */
@@ -1093,11 +1141,15 @@
 				69779BEC2AE68E6900D7A48E /* UIViewController.swift in Sources */,
 				3A0F108929C9BD76002C0084 /* Errors.swift in Sources */,
 				3AE3FB37299162EA00AFFC18 /* PostHogApi.swift in Sources */,
+				DAC699D62CC790D9000D1D6B /* AutocaptureEventProcessing.swift in Sources */,
 				6926DA8E2ADD2876005760D2 /* PostHogContext.swift in Sources */,
 				690FF0AF2AEB9C1400A0B06B /* DateUtils.swift in Sources */,
 				69F518162BAC7F9200F52C14 /* UIView+Util.swift in Sources */,
 				69261D192AD9673500232EC7 /* PostHogBatchUploadInfo.swift in Sources */,
+				DAC699EC2CCA73E5000D1D6B /* ForwardingPickerViewDelegate.swift in Sources */,
+				DA26419C2CC0499300CB427B /* PostHogAutocaptureIntegration.swift in Sources */,
 				69ED1A5C2C7F15F300FE7A91 /* PostHogSessionManager.swift in Sources */,
+				DAC699E52CC8EF57000D1D6B /* PostHogAutoCaptureConfig.swift in Sources */,
 				69F23A742BB3088E001194F6 /* URLSessionSwizzler.swift in Sources */,
 				69F518142BAC7F4300F52C14 /* Date+Util.swift in Sources */,
 				69F5183A2BB2BA8300F52C14 /* UIApplicationTracker.swift in Sources */,

PostHog/Autocapture/AutocaptureEventProcessing.swift

@@ -0,0 +1,131 @@
+//
+//  AutocaptureEventProcessing.swift
+//  PostHog
+//
+//  Created by Yiannis Josephides on 22/10/2024.
+//
+
+#if os(iOS) || targetEnvironment(macCatalyst)
+    import UIKit
+
+    protocol AutocaptureEventProcessing: AnyObject {
+        func process(source: PostHogAutocaptureIntegration.EventData.EventSource, event: PostHogAutocaptureIntegration.EventData)
+    }
+
+    class PostHogAutocaptureEventProcessor: AutocaptureEventProcessing {
+        private weak var postHogInstance: PostHogSDK?
+        private weak var postHogConfig: PostHogConfig?
+        private var debounceTimers: [Int: Timer] = [:]
+
+        init(postHogInstance: PostHogSDK, configuration: PostHogConfig) {
+            self.postHogInstance = postHogInstance
+            self.postHogConfig = configuration
+            PostHogAutocaptureIntegration.addEventProcessor(self)
+        }
+
+        deinit {
+            PostHogAutocaptureIntegration.removeEventProcessor(self)
+        }
+
+        /**
+         Processes an autocapture event, with optional debounce logic for controls that emit frequent events.
+
+         - Parameters:
+            - source: The source of the event (e.g., gesture recognizer, action method, or notification).
+            - event: The autocapture event data, containing properties, screen name, and other metadata.
+
+         If the event has a `debounceInterval` greater than 0, the event is debounced.
+         This is useful for UIControls like `UISlider` that emit frequent value changes, ensuring only the last value is captured.
+         The debounce interval is defined per UIControl by the `ph_autocaptureDebounceInterval` property of `AutoCapturable`
+         */
+        func process(source: PostHogAutocaptureIntegration.EventData.EventSource, event: PostHogAutocaptureIntegration.EventData) {
+            assert(Thread.isMainThread, "Event captured off main thread")
+
+            guard shouldProcess(source: source) else { return }
+
+            let eventHash = event.viewHierarchy.map(\.targetClass).hashValue
+            // debounce frequent UIControl events (e.g., UISlider) to reduce event noise
+            if event.debounceInterval > 0 {
+                debounceTimers[eventHash]?.invalidate() // Keep cancelling existing
+                debounceTimers[eventHash] = Timer.scheduledTimer(withTimeInterval: event.debounceInterval, repeats: false) { [weak self] _ in
+                    self?.handleEventProcessing(source: source, event: event)
+                    self?.debounceTimers.removeValue(forKey: eventHash) // Clean up once fired
+                }
+            } else {
+                handleEventProcessing(source: source, event: event)
+            }
+        }
+
+        private static let viewHierarchyDelimiter = ";"
+        /**
+         Handles the processing of autocapture events by extracting event details, building properties, and sending them to PostHog.
+
+         - Parameters:
+            - source: The source of the event, which could be an action method, gesture recognizer, or notification. Associated values are already mapped to `$event_type` earlier in the chain
+            - event: The event data including view hierarchy, screen name, and other metadata.
+
+         This function extracts event details such as the event type, view hierarchy, and touch coordinates.
+         It creates a structured payload with relevant properties (e.g., tag_name, elements, element_chain) and sends it to the associated PostHog instance for further processing.
+         */
+        private func handleEventProcessing(source: PostHogAutocaptureIntegration.EventData.EventSource, event: PostHogAutocaptureIntegration.EventData) {
+            guard let postHogInstance else { return }
+
+            let eventType: String = switch source {
+            case let .actionMethod(description): description
+            case let .gestureRecognizer(description): description
+            case let .notification(name): name
+            }
+
+            var properties: [String: Any] = [:]
+
+            if let screenName = event.screenName {
+                properties["$screen_name"] = event.screenName
+            }
+
+            let elements = event.viewHierarchy.map { node in
+                [
+                    "text": node.text,
+                    "tag_name": node.targetClass, // required
+                    "order": node.index,
+                    "attributes": [ // required
+                        "attr__class": node.targetClass
+                    ]
+                ]
+            }
+
+            let elementsChain = event.viewHierarchy
+                .map(\.description)
+                .joined(separator: Self.viewHierarchyDelimiter)
+
+            if let coordinates = event.touchCoordinates {
+                properties["$touch_x"] = coordinates.x
+                properties["$touch_y"] = coordinates.y
+            }
+
+            postHogInstance.autocapture(
+                eventType: eventType,
+                elements: elements,
+                elementsChain: elementsChain,
+                properties: properties
+            )
+        }
+
+        /// Determines whether an autocapture event should be processed based on the event source and the current PostHog configuration.
+        ///
+        /// Note: Not sure if we should be checking feature flags yet here
+        ///
+        /// - Parameter source: source to be processed
+        private func shouldProcess(source: PostHogAutocaptureIntegration.EventData.EventSource) -> Bool {
+            guard let postHogConfig, let postHogInstance, postHogInstance.isAutocaptureActive() else { return false }
+
+            switch source {
+            case .actionMethod:
+                return postHogConfig.autocaptureConfig.captureControlActions
+            case .gestureRecognizer:
+                return postHogConfig.autocaptureConfig.captureGestures
+            case .notification:
+                return postHogConfig.autocaptureConfig.captureTextEdits
+            }
+        }
+    }
+#endif