feat: [SDK-5088] record the device gesture as an observability event

DeviceGestureDetector now takes the IObservabilityEventRecorder from the
container and records ObservabilityEvent.DEVICE_GESTURE each time the
gesture is recognised. gesture.result is copied, no_id or disabled, and a
copied event also carries gesture.push_subscription_id, the value that
went on the clipboard.

The copied result is recorded from the main-thread block after the clip is
set, so it never overstates. A gesture under withheld privacy consent
records nothing, because the event ships to the backend.

Tests drive the detector with a recorder spy and pin the attribute names
and values, since the log backend is queried by them.

Author: nan-li

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/core/internal/gesture/DeviceGestureDetector.kt

@@ -11,6 +11,8 @@ import com.onesignal.core.internal.application.IApplicationService
 import com.onesignal.core.internal.config.ConfigModelStore
 import com.onesignal.core.internal.startup.IStartableService
 import com.onesignal.debug.internal.logging.Logging
+import com.onesignal.logger.IObservabilityEventRecorder
+import com.onesignal.logger.ObservabilityEvent
 
 /**
  * Detects the test-device gesture: [REQUIRED_CYCLES] background/foreground cycles within
@@ -28,10 +30,14 @@ import com.onesignal.debug.internal.logging.Logging
  * [com.onesignal.core.internal.config.ConfigModel.sdkRemoteFeatureFlags] list because
  * [com.onesignal.core.internal.features.IFeatureManager] only resolves keys the KMP catalog
  * registers.
+ *
+ * Every recognised gesture also records [ObservabilityEvent.DEVICE_GESTURE], with its outcome
+ * and the copied ID, so the gesture's usage can be measured.
  */
 internal class DeviceGestureDetector(
     private val applicationService: IApplicationService,
     private val configModelStore: ConfigModelStore,
+    private val eventRecorder: IObservabilityEventRecorder,
 ) : IStartableService,
     IApplicationLifecycleHandler {
     /**
@@ -102,12 +108,17 @@ internal class DeviceGestureDetector(
         val config = configModelStore.model
         val subscriptionId = config.pushSubscriptionId
         when {
+            // Not recorded either: nothing about the device may ship before consent.
             config.consentRequired == true && config.consentGiven != true ->
                 Logging.debug("DeviceGestureDetector: gesture detected but privacy consent is not granted")
-            config.sdkRemoteFeatureFlags.any { it.equals(KILL_SWITCH_KEY, ignoreCase = true) } ->
+            config.sdkRemoteFeatureFlags.any { it.equals(KILL_SWITCH_KEY, ignoreCase = true) } -> {
                 Logging.debug("DeviceGestureDetector: gesture detected but disabled remotely")
-            subscriptionId.isNullOrEmpty() || IDManager.isLocalId(subscriptionId) ->
+                recordGesture(GestureResult.DISABLED)
+            }
+            subscriptionId.isNullOrEmpty() || IDManager.isLocalId(subscriptionId) -> {
                 Logging.info("DeviceGestureDetector: gesture detected before the push subscription exists, nothing copied")
+                recordGesture(GestureResult.NO_ID)
+            }
             else -> writeToClipboard(subscriptionId)
         }
     }
@@ -122,10 +133,30 @@ internal class DeviceGestureDetector(
                 // No EXTRA_IS_SENSITIVE: the Android 13+ copy preview is the person's confirmation.
                 clipboard.setPrimaryClip(ClipData.newPlainText(CLIP_LABEL, clipText(subscriptionId)))
                 Logging.info("DeviceGestureDetector: push subscription ID copied to clipboard")
+                recordGesture(GestureResult.COPIED, copiedId = subscriptionId)
             }
         }
     }
 
+    /** Recorded once the outcome is known, so `copied` means the clip was actually set. */
+    private fun recordGesture(
+        result: GestureResult,
+        copiedId: String? = null,
+    ) {
+        val attributes = mutableMapOf(ATTRIBUTE_RESULT to result.wire)
+        if (copiedId != null) {
+            attributes[ATTRIBUTE_PUSH_SUBSCRIPTION_ID] = copiedId
+        }
+        eventRecorder.record(ObservabilityEvent.DEVICE_GESTURE, attributes)
+    }
+
+    /** Wire values of `gesture.result`, which backend queries match on. */
+    private enum class GestureResult(val wire: String) {
+        COPIED("copied"),
+        NO_ID("no_id"),
+        DISABLED("disabled"),
+    }
+
     companion object {
         internal const val REQUIRED_CYCLES = 6
         internal const val WINDOW_MS = 30_000L
@@ -135,6 +166,8 @@ internal class DeviceGestureDetector(
 
         internal const val KILL_SWITCH_KEY = "sdk_device_gesture_disabled"
         private const val CLIP_LABEL = "OneSignal subscription ID"
+        private const val ATTRIBUTE_RESULT = "gesture.result"
+        private const val ATTRIBUTE_PUSH_SUBSCRIPTION_ID = "gesture.push_subscription_id"
 
         /**
          * The `os:` prefix marks the value as a OneSignal ID, for the dashboard's paste target and

OneSignalSDK/onesignal/core/src/test/java/com/onesignal/core/internal/gesture/DeviceGestureDetectorTests.kt

@@ -8,10 +8,14 @@ import androidx.test.core.app.ApplicationProvider
 import br.com.colman.kotest.android.extensions.robolectric.RobolectricTest
 import com.onesignal.core.internal.application.IApplicationLifecycleHandler
 import com.onesignal.core.internal.application.IApplicationService
+import com.onesignal.logger.ILogTelemetry
+import com.onesignal.logger.IObservabilityEventRecorder
+import com.onesignal.logger.ObservabilityEvent
 import com.onesignal.mocks.IOMockHelper
 import com.onesignal.mocks.IOMockHelper.awaitIO
 import com.onesignal.mocks.MockHelper
 import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.collections.shouldBeEmpty
 import io.kotest.matchers.shouldBe
 import io.mockk.every
 import io.mockk.mockk
@@ -20,6 +24,32 @@ import org.robolectric.annotation.Config
 
 private const val SUBSCRIPTION_ID = "aaaabbbb-cccc-dddd-eeee-ffff00001111"
 
+/**
+ * Captures what the detector records so tests can assert the event and its attributes. The
+ * attach/detach/reset side belongs to the logger lifecycle and never reaches the detector.
+ */
+private class RecorderSpy : IObservabilityEventRecorder {
+    private val stored = mutableListOf<Pair<ObservabilityEvent, Map<String, String>>>()
+
+    val recorded: List<Pair<ObservabilityEvent, Map<String, String>>>
+        get() = synchronized(stored) { stored.toList() }
+
+    override fun record(
+        event: ObservabilityEvent,
+        attributes: Map<String, String>,
+    ) {
+        synchronized(stored) { stored.add(event to attributes) }
+    }
+
+    override fun record(event: ObservabilityEvent) = record(event, emptyMap())
+
+    override fun attach(telemetry: ILogTelemetry) = Unit
+
+    override fun detach(telemetry: ILogTelemetry) = Unit
+
+    override fun reset() = Unit
+}
+
 /**
  * Drives the detector through synthetic focus/unfocus sequences with a controlled clock and
  * reads back the real (Robolectric) clipboard. Dwells are in milliseconds; the default cycle
@@ -36,6 +66,7 @@ private class Harness(
 
     val context: Context = ApplicationProvider.getApplicationContext()
     val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+    val recorder = RecorderSpy()
 
     private val handlerSlot = slot<IApplicationLifecycleHandler>()
     val detector: DeviceGestureDetector
@@ -57,7 +88,7 @@ private class Harness(
                 it.consentRequired = consentRequired
                 it.consentGiven = consentGiven
             }
-        detector = DeviceGestureDetector(applicationService, configModelStore)
+        detector = DeviceGestureDetector(applicationService, configModelStore, recorder)
         detector.monotonicMillis = { nowMs }
         detector.start()
     }
@@ -226,4 +257,74 @@ class DeviceGestureDetectorTests : FunSpec({
         awaitIO()
         harness.clipText() shouldBe harness.expectedClip
     }
+
+    // ===== Observability event =====
+    // Every recognised gesture records DEVICE_GESTURE with its outcome, whether or not an ID was
+    // copied, so the backend can answer how often the gesture happens and how often it pays off.
+
+    test("a completed gesture records a copied event carrying the subscription ID") {
+        val harness = Harness()
+
+        // Progress is silent: the event fires on recognition, not per cycle.
+        repeat(5) { harness.cycle() }
+        awaitIO()
+        harness.recorder.recorded.shouldBeEmpty()
+
+        harness.cycle()
+        awaitIO()
+
+        harness.recorder.recorded shouldBe
+            listOf(
+                ObservabilityEvent.DEVICE_GESTURE to
+                    mapOf(
+                        "gesture.result" to "copied",
+                        "gesture.push_subscription_id" to SUBSCRIPTION_ID,
+                    ),
+            )
+    }
+
+    test("the remote kill switch records a disabled result without an ID") {
+        val harness = Harness(remoteFlags = listOf(DeviceGestureDetector.KILL_SWITCH_KEY))
+
+        repeat(6) { harness.cycle() }
+        awaitIO()
+
+        harness.recorder.recorded shouldBe
+            listOf(ObservabilityEvent.DEVICE_GESTURE to mapOf("gesture.result" to "disabled"))
+    }
+
+    test("a missing or local push subscription records a no_id result") {
+        // Both shapes mean the same thing to the backend: the gesture ran before the device had
+        // anything worth pasting.
+        listOf(null, "local-$SUBSCRIPTION_ID").forEach { subscriptionId ->
+            val harness = Harness(subscriptionId = subscriptionId)
+
+            repeat(6) { harness.cycle() }
+            awaitIO()
+
+            harness.recorder.recorded shouldBe
+                listOf(ObservabilityEvent.DEVICE_GESTURE to mapOf("gesture.result" to "no_id"))
+        }
+    }
+
+    test("withheld privacy consent records nothing") {
+        // The event would ship to the backend, and nothing may leave the device before consent.
+        val harness = Harness(consentRequired = true, consentGiven = null)
+
+        repeat(6) { harness.cycle() }
+        awaitIO()
+
+        harness.recorder.recorded.shouldBeEmpty()
+    }
+
+    test("each recognition records its own event") {
+        val harness = Harness()
+
+        repeat(12) { harness.cycle() }
+        awaitIO()
+
+        harness.recorder.recorded.map { it.first } shouldBe
+            listOf(ObservabilityEvent.DEVICE_GESTURE, ObservabilityEvent.DEVICE_GESTURE)
+        harness.recorder.recorded.map { it.second["gesture.result"] } shouldBe listOf("copied", "copied")
+    }
 })