@advenue/react-native 0.9.0 → 1.0.1

package/android/src/main/kotlin/io/advenue/platform/ForegroundTracker.kt

@@ -0,0 +1,90 @@
+package io.advenue.platform
+
+/** What the Android lifecycle told us. */
+internal enum class LifecycleSignal {
+  Started,
+  Stopped,
+  /** `onActivityStopped` where `isChangingConfigurations` was true. */
+  StoppedForConfigChange,
+  /** The background debounce expired without an activity starting. */
+  DebounceElapsed,
+}
+
+internal enum class ForegroundTransition {
+  None,
+  EnteredForeground,
+  /** Arm the debounce; a start before it elapses cancels the background. */
+  ScheduleBackgroundCheck,
+  EnteredBackground,
+}
+
+/**
+ * The foreground/background decision, as a pure state machine over lifecycle
+ * signals — no Android type appears in this file.
+ *
+ * Extracted rather than tested through Robolectric on purpose. Robolectric
+ * reimplements Android, so the interleaving of `onStop(old)` and `onStart(new)`
+ * under rotation would be *its* model, not a device's. Testing the machine
+ * directly makes the logic provable here and leaves exactly one device claim on
+ * the #27 list: that the real callback order matches the signals fed in. Same
+ * pattern as `KeychainStore.interpret` on iOS.
+ *
+ * The case that matters is rotation. A naive started-activity counter goes
+ * 1 → 0 → 1 across a configuration change, which reads as background then
+ * foreground and emits a spurious `session_end`: corrupt session durations and
+ * a phantom pair in the data. Two guards, because either alone leaks — the
+ * configuration-change check, and a 700 ms debounce for the slow rotation on a
+ * low-end device that outruns it. The 700 is not invented; it is
+ * `ProcessLifecycleOwner`'s constant. We cannot take the dependency, but we can
+ * take its number.
+ */
+internal class ForegroundTracker {
+  private var started = 0
+  private var inForeground = false
+  private var backgroundPending = false
+
+  public fun onSignal(signal: LifecycleSignal): ForegroundTransition =
+    when (signal) {
+      LifecycleSignal.Started -> {
+        started += 1
+        // A start always cancels a pending background, whether it came from a
+        // rotation or from the user coming back within the debounce.
+        backgroundPending = false
+        if (!inForeground) {
+          inForeground = true
+          ForegroundTransition.EnteredForeground
+        } else {
+          ForegroundTransition.None
+        }
+      }
+
+      LifecycleSignal.StoppedForConfigChange -> {
+        // The activity is being recreated. It never left the foreground, so
+        // nothing is scheduled and nothing is emitted.
+        if (started > 0) started -= 1
+        ForegroundTransition.None
+      }
+
+      LifecycleSignal.Stopped -> {
+        if (started > 0) started -= 1
+        if (started == 0 && inForeground) {
+          backgroundPending = true
+          ForegroundTransition.ScheduleBackgroundCheck
+        } else {
+          ForegroundTransition.None
+        }
+      }
+
+      LifecycleSignal.DebounceElapsed ->
+        if (backgroundPending && started == 0) {
+          backgroundPending = false
+          inForeground = false
+          ForegroundTransition.EnteredBackground
+        } else {
+          ForegroundTransition.None
+        }
+    }
+}
+
+/** `ProcessLifecycleOwner`'s delay, without the dependency. */
+internal const val BACKGROUND_DEBOUNCE_MS: Long = 700L

package/android/src/main/kotlin/io/advenue/platform/HttpUrlTransport.kt

@@ -0,0 +1,101 @@
+package io.advenue.platform
+
+import io.advenue.core.Clock
+import io.advenue.core.ClientEvent
+import io.advenue.core.EventTransport
+import io.advenue.core.IngestError
+import io.advenue.core.JvmHmacSigner
+import io.advenue.core.Signer
+import io.advenue.core.signRequest
+import io.advenue.core.parseJson
+import io.advenue.core.writeCanonicalJson
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+
+internal const val DEFAULT_ENDPOINT: String = "https://ingest.advenue.io"
+
+/**
+ * Batched ingest over `HttpURLConnection` — dependency-free, and backed by
+ * OkHttp inside Android since 4.4 without being a declared dependency, so the
+ * SDK never joins the host app's version resolution for its HTTP client.
+ *
+ * Throws [IngestError] on a non-2xx so the caller can tell a transient failure
+ * from a poison payload; a transport failure maps to 408, matching sdk-core so
+ * all three SDKs retry exactly the same cases.
+ *
+ * No gzip: the TypeScript transport does not compress, and this port does not
+ * invent behaviour the other implementations do not have.
+ */
+internal class HttpUrlTransport(
+  private val endpoint: String = DEFAULT_ENDPOINT,
+  private val apiKey: String,
+  private val signingSecret: String? = null,
+  private val signer: Signer = JvmHmacSigner(),
+  private val clock: Clock,
+  private val connectTimeoutMs: Int = 15_000,
+  private val readTimeoutMs: Int = 15_000,
+  /**
+   * Receives the app the server reported for an ACCEPTED batch. Purely
+   * diagnostic: it is invoked after the batch is already accepted, and nothing
+   * it does — including throwing — can turn a successful ingest into a failure.
+   */
+  private val onAccepted: (String) -> Unit = {},
+) : EventTransport {
+
+  /**
+   * The exact body this transport would send. Internal so a test can assert the
+   * wire shape without a network round trip, which is the part that has to be
+   * right.
+   */
+  internal fun buildBody(events: List<ClientEvent>): String =
+    writeCanonicalJson(mapOf("apiKey" to apiKey, "events" to events.map { it.toMap() }))
+
+  /** The headers for [body]; empty of signature headers when no secret is set. */
+  internal fun buildHeaders(body: String, timestamp: String): Map<String, String> {
+    val headers = linkedMapOf("content-type" to "application/json")
+    val secret = signingSecret ?: return headers
+    headers["X-Advenue-Timestamp"] = timestamp
+    headers["X-Advenue-Signature"] = signRequest(signer, secret, timestamp, body)
+    return headers
+  }
+
+  override fun send(events: List<ClientEvent>) {
+    val body = buildBody(events)
+    val headers = buildHeaders(body, clock.nowMs().toString())
+
+    val connection = URL("$endpoint/v1/events").openConnection() as HttpURLConnection
+    try {
+      connection.requestMethod = "POST"
+      connection.doOutput = true
+      connection.connectTimeout = connectTimeoutMs
+      connection.readTimeout = readTimeoutMs
+      headers.forEach { (name, value) -> connection.setRequestProperty(name, value) }
+
+      connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+
+      val status =
+        try {
+          connection.responseCode
+        } catch (_: IOException) {
+          // No response at all is a transient failure, not a poison payload.
+          throw IngestError(408)
+        }
+      if (status < 200 || status >= 300) throw IngestError(status)
+
+      // Drain so the connection can be reused rather than torn down, and read
+      // the app the server resolved this API key to.
+      runCatching {
+        val payload = connection.inputStream.use { it.readBytes() }.toString(Charsets.UTF_8)
+        val appId = (parseJson(payload) as? Map<*, *>)?.get("appId") as? String
+        if (!appId.isNullOrEmpty()) onAccepted(appId)
+      }
+    } catch (error: IngestError) {
+      throw error
+    } catch (_: IOException) {
+      throw IngestError(408)
+    } finally {
+      connection.disconnect()
+    }
+  }
+}

package/android/src/main/kotlin/io/advenue/platform/Identity.kt

@@ -0,0 +1,79 @@
+package io.advenue.platform
+
+import android.content.Context
+import android.os.Build
+import android.os.UserManager
+import io.advenue.core.DEVICE_ID_KEY
+import io.advenue.core.INSTALLATION_ID_KEY
+import io.advenue.core.UuidSource
+
+/**
+ * Whether credential-encrypted storage is readable right now.
+ *
+ * Android 7+ **Direct Boot** runs before the first unlock, and the default
+ * storage is unavailable then. Whether a read throws or returns empty is not
+ * asserted here — both are handled the same way, by not reading at all.
+ */
+internal fun interface UnlockProbe {
+  public fun isUnlocked(): Boolean
+}
+
+/**
+ * Production probe. Below API 24 Direct Boot does not exist, so the device is
+ * always considered unlocked. No `androidx.core` dependency: the system service
+ * is enough.
+ */
+internal fun systemUnlockProbe(context: Context): UnlockProbe = UnlockProbe {
+  if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) return@UnlockProbe true
+  runCatching {
+    (context.applicationContext.getSystemService(Context.USER_SERVICE) as? UserManager)
+      ?.isUserUnlocked ?: true
+  }
+    .getOrDefault(true)
+}
+
+internal sealed class IdentityResolution {
+  public data class Resolved(val deviceId: String, val installationId: String) :
+    IdentityResolution()
+
+  /**
+   * The store could not be read. Nothing is minted and nothing starts, so no
+   * event carries an invented identifier. The caller registers for
+   * `ACTION_USER_UNLOCKED` and retries — a deferral with no exit would trade a
+   * phantom id for permanent silence.
+   */
+  public object Deferred : IdentityResolution()
+}
+
+/**
+ * Resolves the pair the SDK stamps on every event.
+ *
+ * Unlike iOS, both halves live in the same place: Android has no
+ * reinstall-durable secure store, so `device_id` dies with the app just as
+ * `installation_id` does. A reinstall is legitimately a new install here, and
+ * returning users are separated by the reattribution layer rather than by
+ * device identity.
+ *
+ * The exposure this guards is narrower than the iOS locked-Keychain hole and is
+ * justified on cost, not parity: Direct Boot only runs components a host app has
+ * explicitly marked `directBootAware`. It is roughly ten lines against minting
+ * a device id belonging to no real device.
+ *
+ * The honest limit: a `SharedPreferences` file corrupted by power loss is
+ * discarded by Android and reads empty, which is indistinguishable from a first
+ * launch. Nothing client-side can defend that; the backend dedup window absorbs
+ * it.
+ */
+internal fun resolveIdentity(
+  store: ScopedStore,
+  unlock: UnlockProbe,
+  uuid: UuidSource,
+): IdentityResolution {
+  // Checked BEFORE any read, so an unreadable store mints nothing at all.
+  if (!unlock.isUnlocked()) return IdentityResolution.Deferred
+
+  val deviceId = store.get(DEVICE_ID_KEY) ?: uuid.next().also { store.set(DEVICE_ID_KEY, it) }
+  val installationId =
+    store.get(INSTALLATION_ID_KEY) ?: uuid.next().also { store.set(INSTALLATION_ID_KEY, it) }
+  return IdentityResolution.Resolved(deviceId, installationId)
+}

package/android/src/main/kotlin/io/advenue/platform/InstallEnrichment.kt

@@ -0,0 +1,197 @@
+package io.advenue.platform
+
+import android.content.Context
+import io.advenue.core.parseInstallReferrer
+import io.advenue.core.referrerProperties
+import io.advenue.plugin.AdvertisingIdSource
+import io.advenue.plugin.AppInstanceIdSource
+import io.advenue.plugin.AttestationSource
+import io.advenue.plugin.InstallReferrerSource
+import io.advenue.core.MetaReferrer
+import io.advenue.core.parseMetaInstallReferrer
+import io.advenue.plugin.PluginRegistry
+import java.security.MessageDigest
+import java.util.concurrent.Callable
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+/**
+ * Spec §3: the install waits this long for the referrer and no longer. Matches
+ * the watchdog the React Native module already uses.
+ *
+ * Waiting is **correct here**, and this is the one place Android inverts iOS. On
+ * iOS, waiting for ATT was wrong because the install could hang forever if the
+ * app never prompts. The Play referrer is a bounded local IPC call and it *is*
+ * the deterministic attribution — an install sent without it is an organic
+ * install. Five seconds against attribution windows measured in hours is noise;
+ * a misclassification is not.
+ */
+internal const val REFERRER_DEADLINE_MS: Long = 5_000
+
+/** A shorter budget for the enrichment that is not attribution-critical. */
+internal const val ENRICHMENT_DEADLINE_MS: Long = 3_000
+
+internal data class Enrichment(
+  val referrerProperties: Map<String, Any?>? = null,
+  val network: String? = null,
+  val campaign: String? = null,
+  val gaid: String? = null,
+  val limitAdTracking: Boolean = false,
+  val appSetId: String? = null,
+  val appInstanceId: String? = null,
+  val attestationToken: String? = null,
+  /** Meta install-referrer properties, in the names the server reads. */
+  val metaProperties: Map<String, Any?>? = null,
+)
+
+/**
+ * The plugins the collector draws on, injected so the deadline behaviour is
+ * testable without Play Services — none of which a JVM test or an emulator can
+ * exercise honestly.
+ */
+internal data class EnrichmentSources(
+  val referrer: InstallReferrerSource? = null,
+  val advertisingId: AdvertisingIdSource? = null,
+  val attestation: AttestationSource? = null,
+  val appInstanceId: AppInstanceIdSource? = null,
+) {
+  public companion object {
+    /** Whatever the consumer put on the classpath, resolved once. */
+    public fun discovered(): EnrichmentSources =
+      EnrichmentSources(
+        referrer = PluginRegistry.load(PluginRegistry.PLAY_REFERRER),
+        advertisingId = PluginRegistry.load(PluginRegistry.PLAY_IDENTITY),
+        attestation = PluginRegistry.load(PluginRegistry.PLAY_INTEGRITY),
+        appInstanceId = PluginRegistry.load(PluginRegistry.FIREBASE),
+      )
+  }
+}
+
+/**
+ * Runs the plugin reads concurrently behind a hard deadline and returns what
+ * arrived. A source still running contributes nothing and its value rides a
+ * later event rather than holding the install.
+ */
+internal fun collectEnrichment(
+  context: Context,
+  deviceId: String,
+  sources: EnrichmentSources,
+  deadlineMs: Long = REFERRER_DEADLINE_MS,
+  /** Meta app id. Null disables the Meta provider query entirely. */
+  fbAppId: String? = null,
+): Enrichment {
+  // Five, because there are five sources. A pool sized to four would leave the
+  // fifth waiting for a thread while the shared deadline ran down, and a source
+  // that never got to run contributes nothing — silently, which is the failure
+  // this file is otherwise built to avoid.
+  val pool = Executors.newFixedThreadPool(5) { r -> Thread(r, "advenue-enrich").apply { isDaemon = true } }
+  try {
+    val referrerTask =
+      sources.referrer?.let { pool.submit(Callable { it.read(context, deadlineMs) }) }
+    val adTask = sources.advertisingId?.let { pool.submit(Callable { it.read(context) }) }
+    val instanceTask =
+      sources.appInstanceId?.let {
+        pool.submit(Callable { it.read(context, ENRICHMENT_DEADLINE_MS) })
+      }
+    val attestTask =
+      sources.attestation?.let {
+        // sha256Hex(deviceId) — the server re-derives the same string and
+        // compares byte for byte, so no app id is hashed in.
+        val hash = sha256Hex(deviceId)
+        pool.submit(Callable { it.token(context, hash) })
+      }
+
+    // Meta's install referrer. Not a plugin: it needs no vendor dependency,
+    // only the <queries> entries the SDK's own manifest declares. A content
+    // provider on another app can hang, so it rides the same deadline.
+    val metaTask =
+      fbAppId?.let { id -> pool.submit(Callable { readMetaInstallReferrer(context, id) }) }
+
+    val deadline = System.currentTimeMillis() + deadlineMs
+    fun <T> settle(task: java.util.concurrent.Future<T>?): T? {
+      task ?: return null
+      val remaining = deadline - System.currentTimeMillis()
+      if (remaining <= 0) return null
+      return runCatching { task.get(remaining, TimeUnit.MILLISECONDS) }.getOrNull()
+    }
+
+    val referrer = settle(referrerTask)
+    val parsed = referrer?.let { parseInstallReferrer(it.referrer) }
+    val ad = settle(adTask)
+
+    return Enrichment(
+      referrerProperties =
+        referrer?.let {
+          val props =
+            referrerProperties(
+              referrer = it.referrer,
+              clickTimestamp = it.clickTimestamp,
+              installTimestamp = it.installTimestamp,
+              clickServerTimestamp = it.clickServerTimestamp,
+              installServerTimestamp = it.installServerTimestamp,
+              googlePlayInstant = it.googlePlayInstant,
+            )
+              .toMutableMap()
+          parsed?.gclid?.let { value -> props["gclid"] = value }
+          parsed?.fbclid?.let { value -> props["fbclid"] = value }
+          props
+        },
+      network = parsed?.network,
+      campaign = parsed?.campaign,
+      gaid = ad?.gaid,
+      limitAdTracking = ad?.limitAdTracking ?: false,
+      appSetId = ad?.appSetId,
+      appInstanceId = settle(instanceTask),
+      attestationToken = settle(attestTask),
+      metaProperties = settle(metaTask)?.let(::parseMetaColumns)?.let(::metaReferrerProperties),
+    )
+  } finally {
+    pool.shutdownNow()
+  }
+}
+
+/**
+ * The provider's columns, as the parser wants them.
+ *
+ * `readMetaInstallReferrer` returns what the cursor held; the shape of the
+ * referrer string itself — JSON claim or utm query string — is the parser's
+ * problem, and keeping the two apart is what lets the parser be tested without
+ * a content provider.
+ */
+private fun parseMetaColumns(columns: Map<String, Any?>): MetaReferrer? {
+  val raw = columns["installReferrer"] as? String ?: return null
+  return parseMetaInstallReferrer(
+    raw = raw,
+    isClickThrough = columns["isClickThrough"] == true,
+    actualTimestamp = (columns["actualTimestamp"] as? Number)?.toLong() ?: 0L,
+  )
+}
+
+/**
+ * The Meta referrer as event properties, in the exact names the server reads.
+ *
+ * All four, not two. `meta-referrer-claim.ts` reads `metaReferrerData` and
+ * `metaReferrerNonce` to find the claim, and then `metaReferrerIsCt` to decide
+ * click-through against view-through and `metaReferrerTimestamp` to validate
+ * the claim's age. The React Native SDK sent only the first two before the
+ * inversion, so every claim it ever produced was read as a view-through with no
+ * age check — a half-wired path that looked like it worked.
+ */
+internal fun metaReferrerProperties(meta: MetaReferrer): Map<String, Any?> = buildMap {
+  put("metaInstallReferrer", meta.raw)
+  meta.encryptedData?.let { put("metaReferrerData", it) }
+  meta.nonce?.let { put("metaReferrerNonce", it) }
+  put("metaReferrerIsCt", if (meta.isClickThrough) 1 else 0)
+  if (meta.timestamp > 0L) put("metaReferrerTimestamp", meta.timestamp)
+}
+
+/** Lowercase hex SHA-256, the form the server's verdict mapping re-derives. */
+internal fun sha256Hex(value: String): String {
+  val digest = MessageDigest.getInstance("SHA-256").digest(value.toByteArray(Charsets.UTF_8))
+  val out = StringBuilder(digest.size * 2)
+  for (byte in digest) {
+    out.append("0123456789abcdef"[(byte.toInt() shr 4) and 0xF])
+    out.append("0123456789abcdef"[byte.toInt() and 0xF])
+  }
+  return out.toString()
+}

package/android/src/main/kotlin/io/advenue/platform/InstallScopedStore.kt

@@ -0,0 +1,96 @@
+package io.advenue.platform
+
+import android.content.Context
+import io.advenue.core.DEVICE_ID_KEY
+import io.advenue.core.INSTALLATION_ID_KEY
+import io.advenue.core.INSTALL_SENT_KEY
+import io.advenue.core.QUEUE_KEY
+import java.io.File
+
+/**
+ * The three keys that define the installation boundary, kept in
+ * `noBackupFilesDir` — the one directory Android excludes from backup with no
+ * manifest cooperation.
+ *
+ * Auto Backup restores app state into a **reinstall**. A restored `install_sent`
+ * means that installation's install event never fires again: a lost install,
+ * which is strictly worse than a duplicate the backend dedup window absorbs. A
+ * restored `device_id` is worse still on a *new phone*, where two physical
+ * devices would then report one identity.
+ *
+ * A library cannot reliably alter the app's backup rules —
+ * `android:dataExtractionRules` is an application-level attribute and conflicts
+ * in manifest merging — so this is not enforcement by configuration. It is
+ * enforcement by choosing a directory the platform already excludes.
+ */
+/**
+ * The install-scoped read/write surface, as an interface so identity resolution
+ * — the part carrying the Direct Boot decision — is testable without a Context.
+ */
+internal interface ScopedStore {
+  public fun get(key: String): String?
+
+  public fun set(key: String, value: String)
+}
+
+internal class InstallScopedStore(context: Context) : ScopedStore {
+  private val app = context.applicationContext
+
+  /**
+   * Reads the file, falling back **once** to the legacy SharedPreferences key
+   * and migrating it.
+   *
+   * Without this read-through, an app updating from the RN SDK reads null for
+   * its own device id and install flag: every device looks new and every
+   * installation fires a duplicate install with a fresh installation id, which
+   * no server-side guard can absorb. The legacy key is deleted only after a
+   * successful write — leaving it would let Auto Backup restore it into a
+   * future reinstall, which is exactly what this directory exists to prevent.
+   */
+  override fun get(key: String): String? =
+    runCatching {
+      val file = fileFor(key) ?: return null
+      if (file.exists()) return file.readText()
+
+      val legacy = legacyPrefs()?.getString(key, null) ?: return null
+      runCatching {
+        file.writeText(legacy)
+        legacyPrefs()?.edit()?.remove(key)?.apply()
+      }
+      legacy
+    }
+      .getOrNull()
+
+  override fun set(key: String, value: String) {
+    runCatching { fileFor(key)?.writeText(value) }
+  }
+
+  public fun remove(key: String) {
+    runCatching { fileFor(key)?.delete() }
+  }
+
+  private fun legacyPrefs() =
+    runCatching { app.getSharedPreferences(ADVENUE_SUITE, Context.MODE_PRIVATE) }.getOrNull()
+
+  private fun fileFor(key: String): File? {
+    val name = FILE_NAMES[key] ?: return null
+    val dir = runCatching { app.noBackupFilesDir }.getOrNull() ?: return null
+    return File(dir, name)
+  }
+
+  public companion object {
+    private val FILE_NAMES =
+      mapOf(
+        DEVICE_ID_KEY to "advenue-device-id",
+        INSTALLATION_ID_KEY to "advenue-installation-id",
+        INSTALL_SENT_KEY to "advenue-install-sent",
+        // B4: kuyruk blob'u (GAID'li olay gövdeleri) yedekten çıkar — geri
+        // yüklenen kuyruk hem PII sızıntısı hem de bayat olay yağmurudur.
+        // Eski SharedPreferences anahtarı ilk okumada migrate edilir.
+        QUEUE_KEY to "advenue-queue",
+      )
+
+    /** The keys this store owns; everything else belongs in [PreferencesStore]. */
+    public val INSTALL_SCOPED_KEYS: Set<String> = FILE_NAMES.keys
+  }
+}

package/android/src/main/kotlin/io/advenue/platform/LifecycleBridge.kt

@@ -0,0 +1,72 @@
+package io.advenue.platform
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+
+/**
+ * Turns `ActivityLifecycleCallbacks` into the signals [ForegroundTracker]
+ * understands, and owns the debounce timer.
+ *
+ * `androidx.lifecycle` would give this for free and would also be a dependency
+ * the host app's Gradle resolution has to accommodate, which for a base SDK is
+ * the thing to avoid. All the judgement lives in the tracker; this file is
+ * plumbing.
+ */
+internal class LifecycleBridge(
+  private val application: Application,
+  private val onForeground: () -> Unit,
+  private val onBackground: () -> Unit,
+) : Application.ActivityLifecycleCallbacks {
+  private val tracker = ForegroundTracker()
+  private val handler = Handler(Looper.getMainLooper())
+  private val debounce = Runnable { apply(tracker.onSignal(LifecycleSignal.DebounceElapsed)) }
+
+  fun start() {
+    application.registerActivityLifecycleCallbacks(this)
+  }
+
+  fun stop() {
+    handler.removeCallbacks(debounce)
+    application.unregisterActivityLifecycleCallbacks(this)
+  }
+
+  override fun onActivityStarted(activity: Activity) {
+    handler.removeCallbacks(debounce)
+    apply(tracker.onSignal(LifecycleSignal.Started))
+  }
+
+  override fun onActivityStopped(activity: Activity) {
+    // A rotation is not a background. Checked here as well as behind the
+    // debounce, because a slow rotation on a low-end device can outrun 700 ms.
+    val signal =
+      if (activity.isChangingConfigurations) {
+        LifecycleSignal.StoppedForConfigChange
+      } else {
+        LifecycleSignal.Stopped
+      }
+    apply(tracker.onSignal(signal))
+  }
+
+  private fun apply(transition: ForegroundTransition) {
+    when (transition) {
+      ForegroundTransition.EnteredForeground -> onForeground()
+      ForegroundTransition.EnteredBackground -> onBackground()
+      ForegroundTransition.ScheduleBackgroundCheck ->
+        handler.postDelayed(debounce, BACKGROUND_DEBOUNCE_MS)
+      ForegroundTransition.None -> Unit
+    }
+  }
+
+  override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?): Unit = Unit
+
+  override fun onActivityResumed(activity: Activity): Unit = Unit
+
+  override fun onActivityPaused(activity: Activity): Unit = Unit
+
+  override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle): Unit = Unit
+
+  override fun onActivityDestroyed(activity: Activity): Unit = Unit
+}

package/android/src/main/kotlin/io/advenue/platform/PreferencesStore.kt

@@ -0,0 +1,32 @@
+package io.advenue.platform
+
+import android.content.Context
+import io.advenue.core.KeyValueStore
+
+/**
+ * A dedicated preferences file, so SDK keys never mix with the host app's. The
+ * name matches the RN SDK's, because the RN inversion has to read what it wrote.
+ */
+internal const val ADVENUE_SUITE: String = "io.advenue.sdk"
+
+/**
+ * The general-purpose store: queue, session state, consent and user id.
+ *
+ * Deliberately NOT the home of the install-scoped keys. Auto Backup can restore
+ * this file into a reinstall, and those three keys define the installation
+ * boundary — see [InstallScopedStore].
+ */
+internal class PreferencesStore(context: Context) : KeyValueStore {
+  private val prefs =
+    context.applicationContext.getSharedPreferences(ADVENUE_SUITE, Context.MODE_PRIVATE)
+
+  override fun getString(key: String): String? = runCatching { prefs.getString(key, null) }.getOrNull()
+
+  override fun setString(key: String, value: String) {
+    runCatching { prefs.edit().putString(key, value).apply() }
+  }
+
+  override fun remove(key: String) {
+    runCatching { prefs.edit().remove(key).apply() }
+  }
+}