feat: richer click analytics (event.id/screen_id/screen_name, ldClick) + instrumentation gating (#229)

## Summary

Enhances click/tap analytics on iOS and makes invasive touch
instrumentation honor the `instrumentation` config.

- **`event.id` via `ldId`/`ldClick`**: explicit developer-supplied
identifier takes precedence over derived platform ids (`UIView.ldId(_:)`
for UIKit, `.ldClick(_:)` for SwiftUI, resolved through a non-consuming
`LdClickRegistry`).
- **`event.screen_id` + `event.screen_name`**: stamped on both OTel
`click` spans and Session Replay click events; `screen_name` threaded
from the `ScreenStack`.
- **Manual `trackClick` API** mirroring the auto-captured click shape.
- **`Instrumentation.enabled` / `.disabled`** convenience accessors.
- **Touch-capture gating**: the `UIWindow.sendEvent` swizzle +
hit-testing now install only when `instrumentation.userTaps` is enabled
**or** Session Replay is recording (SR self-starts the shared,
idempotent manager). With both off, no swizzle/hit-testing is installed.
- Fix `UIWindowSwizzleSource` `isActive` idempotency.

## Test plan

- [ ] `LaunchDarklyObservability` + `LaunchDarklySessionReplay` build
(simulator)
- [ ] Unit tests (`LdClickRegistryTests`, `ClickSpanTests`) pass
- [ ] TestApp: taps emit `event.id` (ldId), `event.screen_id`,
`event.screen_name` on spans and SR
- [ ] `instrumentation: .disabled` with SR off ⇒ no swizzle/hit-testing

Made with [Cursor](https://cursor.com)

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: abelonogov-ld

Sources/LaunchDarklyObservability/API/LDObserve.swift

@@ -75,4 +75,8 @@ extension LDObserve: Observe {
     public func trackScreenView(name: String, screenClass: String?, screenId: String?, category: String?, properties: [String: Any]?) {
         client.trackScreenView(name: name, screenClass: screenClass, screenId: screenId, category: category, properties: properties)
     }
+
+    public func trackClick(id: String?, tag: String?, text: String?, screenId: String?, x: Int?, y: Int?, properties: [String: Any]?) {
+        client.trackClick(id: id, tag: tag, text: text, screenId: screenId, x: x, y: y, properties: properties)
+    }
 }

Sources/LaunchDarklyObservability/API/ObservabilityOptions.swift

@@ -159,27 +159,39 @@ public struct ObservabilityOptions {
         let memory: FeatureFlag
         let memoryWarnings: FeatureFlag
         let cpu: FeatureFlag
-        /// Whether to emit legacy launch-time performance metrics. This currently only has an
-        /// effect on Android (TTID/TTFD histograms); on iOS the legacy per-scene launch-time
-        /// metric was refactored into the `app_launch` span, so this flag is presently inert on
-        /// iOS and is retained for cross-platform parity (it is propagated as a single option from
-        /// the Flutter SDK) and possible future use. The `app.start` span event on `app_launch`
-        /// (cold/warm via `start.type`, with `start.duration_ms`) is always attached when
-        /// ``Analytics/appLaunch`` is enabled and is never gated by this flag. Defaults to `.disabled`.
+        /// Whether to emit launch-time performance telemetry. On Android this also gates the legacy
+        /// TTID/TTFD histograms. On both platforms it gates the `app.start` span event on `app_launch`
+        /// (cold/warm via `start.type`, with `start.duration_ms`): when this flag is disabled the
+        /// `app.start` event is omitted and the `app_launch` span is anchored at the launch-detection
+        /// time (rather than back-dated to process start) so it carries no startup duration. The
+        /// `app_launch` span itself (with `event.launch_type` and version fields) is still emitted when
+        /// ``Analytics/appLaunch`` is enabled. Defaults to `.disabled`.
         let launchTimes: FeatureFlag
         /// Whether to automatically detect screen changes by swizzling
         /// `UIViewController`. This drives both the `screen_view` span (gated
         /// separately by ``Analytics/screenViews``) and Session Replay `Navigate`
         /// events. Defaults to `.enabled`.
         let screens: FeatureFlag
 
+        /// Every automatic instrumentation feature enabled.
+        public static var enabled: Self {
+            .init(urlSession: .enabled, userTaps: .enabled, memory: .enabled, memoryWarnings: .enabled, cpu: .enabled, launchTimes: .enabled, screens: .enabled)
+        }
+        
+        /// Every automatic instrumentation feature disabled. Note this also turns off user-tap
+        /// detection (so no `click` spans are emitted regardless of ``Analytics/taps``) and
+        /// automatic screen detection (so no `screen_view`/Session Replay `Navigate` events).
+        public static var disabled: Self {
+            .init(urlSession: .disabled, userTaps: .disabled, memory: .disabled, memoryWarnings: .disabled, cpu: .disabled, launchTimes: .disabled, screens: .disabled)
+        }
+        
         public init(
             urlSession: FeatureFlag = .disabled,
             userTaps: FeatureFlag = .enabled,
             memory: FeatureFlag = .disabled,
             memoryWarnings: FeatureFlag = .disabled,
             cpu: FeatureFlag = .disabled,
-            launchTimes: FeatureFlag = .disabled,
+            launchTimes: FeatureFlag = .enabled,
             screens: FeatureFlag = .enabled
         ) {
             self.urlSession = urlSession
@@ -216,8 +228,10 @@ public struct ObservabilityOptions {
         /// analytics taxonomy app-lifecycle events.
         let appLifecycle: FeatureFlag
         /// Whether to emit an `app_launch` span (with `event.launch_type` and version
-        /// fields, plus an `app.start` span event for the cold/warm startup dimension)
-        /// once per process launch. Maps to the analytics taxonomy `app_launch` event.
+        /// fields) once per process launch. Maps to the analytics taxonomy `app_launch`
+        /// event. The cold/warm startup dimension (`app.start` span event with
+        /// `start.type`/`start.duration_ms`) is attached only when
+        /// ``Instrumentation/launchTimes`` is also enabled.
         let appLaunch: FeatureFlag
 
         public static var enabled: Self {

Sources/LaunchDarklyObservability/API/Observe.swift

@@ -36,6 +36,23 @@ public protocol Observe: AnyObject, MetricsApi, LogsApi, TracesApi, ObserveConte
     ///     attached at lower precedence than the reserved `event.*` fields, so
     ///     they can never clobber the taxonomy.
     func trackScreenView(name: String, screenClass: String?, screenId: String?, category: String?, properties: [String: Any]?)
+    /// Manually record a `click` event as a `click` span.
+    ///
+    /// Use this to reproduce the taxonomy `click` event for interactions that automatic
+    /// tap capture cannot observe. Emitted through the same `analytics.taps` gate as
+    /// automatic click spans.
+    /// - Parameters:
+    ///   - id: Stable element identifier (`event.id`).
+    ///   - tag: Element tag/class (`event.tag`), e.g. `UIButton`.
+    ///   - text: Visible label/text of the element (`event.text`).
+    ///   - screenId: Stable screen id (`event.screen_id`). When `nil`, the current tracked
+    ///     screen id is used so the click correlates with the active `screen_view`.
+    ///   - x: Tap x coordinate in screen pixels (`event.x`).
+    ///   - y: Tap y coordinate in screen pixels (`event.y`).
+    ///   - properties: Optional custom attributes (same conversion rules as a `track`
+    ///     event's `properties`). Attached at lower precedence than the reserved `event.*`
+    ///     fields, so they can never clobber the taxonomy.
+    func trackClick(id: String?, tag: String?, text: String?, screenId: String?, x: Int?, y: Int?, properties: [String: Any]?)
 }
 
 extension Observe {
@@ -57,6 +74,12 @@ extension Observe {
     public func trackScreenView(name: String, screenClass: String?, screenId: String?, category: String?) {
         trackScreenView(name: name, screenClass: screenClass, screenId: screenId, category: category, properties: nil)
     }
+
+    /// Convenience: record a `click` with the common element fields. The current screen id
+    /// is used unless `screenId` is supplied.
+    public func trackClick(id: String?, tag: String? = nil, text: String? = nil, screenId: String? = nil) {
+        trackClick(id: id, tag: tag, text: text, screenId: screenId, x: nil, y: nil, properties: nil)
+    }
 }
 
 /// Context for transfer data from Observability to SessionReplay during initialization

Sources/LaunchDarklyObservability/API/SemanticConvention.swift

@@ -31,6 +31,7 @@ public enum SemanticConvention {
     public static let startDurationMs = "start.duration_ms"
     public static let eventScreenClass = "event.screen_class"
     public static let eventScreenId = "event.screen_id"
+    public static let eventScreenName = "event.screen_name"
     public static let eventPreviousScreen = "event.previous_screen"
     public static let eventCategory = "event.category"
     public static let eventType = "event.type"

Sources/LaunchDarklyObservability/API/View+ldClick.swift

@@ -0,0 +1,41 @@
+#if canImport(UIKit)
+import SwiftUI
+
+public extension View {
+    /// Tags this SwiftUI element so an auto-captured `click` event reports `event.id == id` when the
+    /// user taps it. Prefer a human-readable, stable id (e.g. `"checkout.pay_button"`).
+    ///
+    /// Unlike approaches that bridge the SwiftUI view tree into UIKit, this attaches a SwiftUI tap
+    /// gesture that fires during the tap and records the id; the SDK's interaction capture then uses
+    /// it. It relies only on public SwiftUI gesture APIs, so it is robust across SwiftUI/iOS versions,
+    /// and it does not modify `accessibilityIdentifier` or the view hierarchy. The underlying control
+    /// stays fully interactive (the gesture is attached simultaneously).
+    func ldClick(_ id: String) -> some View {
+        modifier(LdClickModifier(id: id))
+    }
+}
+
+private struct LdClickModifier: ViewModifier {
+    let id: String
+
+    @ViewBuilder
+    func body(content: Content) -> some View {
+        if #available(iOS 16.0, tvOS 16.0, *) {
+            // `.global` is the root of the SwiftUI hierarchy: it matches UIKit window coordinates
+            // for a full-screen window but is screen-relative otherwise. The interaction resolver
+            // reconciles both spaces when matching, so taps still resolve under iPad multitasking.
+            content.simultaneousGesture(
+                SpatialTapGesture(coordinateSpace: .global).onEnded { value in
+                    LdClickRegistry.shared.record(id: id, location: value.location)
+                }
+            )
+        } else {
+            content.simultaneousGesture(
+                TapGesture().onEnded {
+                    LdClickRegistry.shared.record(id: id, location: nil)
+                }
+            )
+        }
+    }
+}
+#endif

Sources/LaunchDarklyObservability/API/View+ldId.swift

@@ -0,0 +1,15 @@
+#if canImport(UIKit)
+import UIKit
+
+public extension UIView {
+    /// Tags this view with a stable analytics identifier used as `event.id` for auto-captured
+    /// `click` events on this view (or its descendants, when the tap resolves to a child). Prefer a
+    /// human-readable, stable id (e.g. `"checkout.pay_button"`). Takes precedence over
+    /// `accessibilityIdentifier`.
+    ///
+    /// For SwiftUI, use the `.ldClick(_:)` view modifier instead.
+    func ldId(_ id: String) {
+        LdIdStorage.set(self, id: id)
+    }
+}
+#endif

Sources/LaunchDarklyObservability/Client/NoOpObservabilityService.swift

@@ -25,6 +25,8 @@ final class NoOpObservabilityService: Observe {
     func track(key: String, properties: [String: Any]?, metricValue: Double?) {}
 
     func trackScreenView(name: String, screenClass: String?, screenId: String?, category: String?, properties: [String: Any]?) {}
+
+    func trackClick(id: String?, tag: String?, text: String?, screenId: String?, x: Int?, y: Int?, properties: [String: Any]?) {}
 }
 
 extension NoOpObservabilityService {

Sources/LaunchDarklyObservability/Client/ObservabilityService.swift

@@ -39,7 +39,7 @@ final class ObservabilityService: InternalObserve {
     private var instruments = [AutoInstrumentation]()
 
     private let userInteractionManager: UserInteractionManager
-    private let screenStack = ScreenStack()
+    private let screenStack: ScreenStack
     private var screenViewManager: ScreenViewManager?
     /// Broadcasts each recorded screen view so Session Replay can emit `Navigate` events.
     private let screenViewSubject = PassthroughSubject<ScreenViewEvent, Never>()
@@ -203,10 +203,21 @@ final class ObservabilityService: InternalObserve {
         // `click` span. Capture still flows to Session Replay regardless of either flag.
         let userTapsEnabled = options.instrumentation.userTaps.isEnabled
         let publishTaps = options.analytics.taps.isEnabled
-        let userInteractionManager = UserInteractionManager(options: options, sessionManaging: sessionManager) { interaction in
+        // Created as a local so the tap closure can read the current screen id without
+        // capturing `self` (which isn't fully initialized yet at this point in `init`).
+        let screenStack = ScreenStack()
+        self.screenStack = screenStack
+        let userInteractionManager = UserInteractionManager(
+            options: options,
+            sessionManaging: sessionManager,
+            // The active screen is read once at tap time and stamped onto the interaction, so the
+            // OTel span here and the Session Replay click event report the identical screen.
+            screenInfoProvider: { (screenStack.currentId, screenStack.current) }
+        ) { interaction in
             guard userTapsEnabled else { return }
             guard publishTaps else { return }
-            interaction.startEndSpan(tracer: tracerDecorator)
+            // Correlate the tap with the active screen (taxonomy §4.1 `event.screen_id`).
+            interaction.startEndSpan(tracer: tracerDecorator, screenId: interaction.screenId, screenName: interaction.screenName)
         }
         self.userInteractionManager = userInteractionManager
 
@@ -292,7 +303,13 @@ extension ObservabilityService {
             )
         }
 
-        userInteractionManager.start()
+        // The touch-capture hook (UIWindow.sendEvent swizzle + hit-testing) is invasive, so it is
+        // only installed when something needs it: tap detection here (gated by
+        // `instrumentation.userTaps`) or Session Replay, which starts the same shared manager
+        // itself. With both off, no swizzle or hit-testing is installed.
+        if options.instrumentation.userTaps.isEnabled {
+            userInteractionManager.start()
+        }
 
         if options.instrumentation.screens.isEnabled {
             screenViewManager?.start()
@@ -464,6 +481,38 @@ extension ObservabilityService: Observe {
             )
         )
     }
+
+    /// Manually emit a `click` span, mirroring the automatic tap instrumentation. Use this
+    /// to reproduce the taxonomy `click` event for interactions automatic capture can't observe.
+    ///
+    /// Gated by `analytics.taps` (the same flag as automatic click spans). When `screenId` is
+    /// `nil`, the current tracked screen id is used so the click correlates with the active
+    /// `screen_view`. Reserved `event.*` fields take precedence over caller `properties`,
+    /// matching the `screen_view`/`track` precedence model.
+    func trackClick(id: String?, tag: String?, text: String?, screenId: String?, x: Int?, y: Int?, properties: [String: Any]?) {
+        guard options.analytics.taps.isEnabled else { return }
+
+        let spanAttributes = ClickAttributes.build(
+            id: id,
+            tag: tag,
+            text: text,
+            // Default to the current screen so the click correlates with the active `screen_view`.
+            screenId: screenId ?? screenStack.currentId,
+            screenName: screenStack.current,
+            x: x,
+            y: y,
+            contextKeyAttributes: cachedContextKeyAttributes,
+            properties: properties?.toOtelAttributes() ?? [:]
+        )
+
+        // Mirror the automatic tap span: a CLIENT-kind `click` span built via the decorator.
+        let builder = tracerDecorator.spanBuilder(spanName: SemanticConvention.clickSpanName)
+        builder.setSpanKind(spanKind: .client)
+        for (key, value) in spanAttributes {
+            builder.setAttribute(key: key, value: value)
+        }
+        builder.startSpan().end()
+    }
 }
 
 extension ObservabilityService: TrackEmitting {
@@ -644,14 +693,18 @@ extension ObservabilityService: TrackEmitting {
         // load (`AppStartTime`) and end it at the launch-detection time carried by the signal, so
         // analytics timestamps reflect the real startup window and aren't skewed by SDK init work.
         let launchTime = Date(timeIntervalSince1970: signal.timestamp)
-        let spanStart = min(AppStartTime.stats.startDate, launchTime)
+        // The startup-performance dimension (cold/warm `start.type` + `start.duration_ms`) is gated by
+        // `instrumentation.launchTimes`. When it is off we also anchor the span at the launch-detection
+        // time instead of back-dating it to process start, so the span window carries no startup
+        // duration and `start.duration_ms` can't be recovered from it.
+        let includeLaunchTime = options.instrumentation.launchTimes.isEnabled
+        let spanStart = includeLaunchTime ? min(AppStartTime.stats.startDate, launchTime) : launchTime
 
         let span = tracer.startSpan(name: SemanticConvention.appLaunchSpanName, attributes: spanAttributes, startTime: spanStart)
         // Taxonomy §4.6: cold/warm lives on the `app.start` span event (orthogonal to
-        // `event.launch_type`). Always attach when known under `analytics.appLaunch`.
-        // `instrumentation.launchTimes` is inert on iOS (the legacy per-scene launch metric was
-        // folded into this span) and intentionally never gated this event.
-        if let startType = signal.startType {
+        // `event.launch_type`), attached under `analytics.appLaunch` and gated by
+        // `instrumentation.launchTimes`.
+        if includeLaunchTime, let startType = signal.startType {
             var eventAttributes: [String: AttributeValue] = [
                 SemanticConvention.startType: .string(startType.rawValue)
             ]