@advenue/react-native 0.8.0 → 1.0.0

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,91 @@
+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 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",
+      )
+
+    /** 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() }
+  }
+}

package/android/src/main/kotlin/io/advenue/plugin/Contracts.kt

@@ -0,0 +1,67 @@
+package io.advenue.plugin
+
+import android.content.Context
+
+/**
+ * The capability contracts each plugin artifact implements.
+ *
+ * The base declares them and never depends on Play Services or Firebase, so an
+ * app on Amazon, Huawei or F-Droid uses the base unchanged. A plugin brings its
+ * own vendor dependency and talks to it with full compile-time typing — the
+ * reflection is one lookup of the plugin's own class, not a wrapper around every
+ * vendor call.
+ */
+
+/** Play Install Referrer. */
+public interface InstallReferrerSource {
+  /**
+   * Blocking; the caller runs it off the main thread with its own deadline.
+   * Returns null when the referrer is unavailable, which is best-effort by
+   * design — an install with no referrer is organic, not a failure.
+   */
+  public fun read(context: Context, timeoutMs: Long): ReferrerResult?
+}
+
+public data class ReferrerResult(
+  val referrer: String,
+  /** Device clock: `referrerClickTimestampSeconds`. */
+  val clickTimestamp: Long,
+  /** Device clock: `installBeginTimestampSeconds`. */
+  val installTimestamp: Long,
+  /** Play's server clock; 0 when the install is unverified. */
+  val clickServerTimestamp: Long,
+  val installServerTimestamp: Long,
+  val googlePlayInstant: Boolean,
+)
+
+/** GAID and App Set ID. */
+public interface AdvertisingIdSource {
+  /** Blocking; the caller runs it off the main thread. */
+  public fun read(context: Context): AdvertisingId?
+}
+
+public data class AdvertisingId(
+  val gaid: String?,
+  val limitAdTracking: Boolean,
+  /**
+   * Developer-scoped, non-advertising. First-party fraud and dedup only —
+   * Google forbids using it for ads or measurement.
+   */
+  val appSetId: String?,
+)
+
+/** Play Integrity Standard API. */
+public interface AttestationSource {
+  /**
+   * [requestHash] is `sha256Hex(deviceId)`. The server re-derives the same
+   * string and compares it byte for byte, so no app id is hashed in: the token
+   * is decoded against this app's Play package name, which binds the app
+   * already.
+   */
+  public fun token(context: Context, requestHash: String): String?
+}
+
+/** Firebase Analytics App Instance ID. */
+public interface AppInstanceIdSource {
+  public fun read(context: Context, timeoutMs: Long): String?
+}

package/android/src/main/kotlin/io/advenue/plugin/FirebaseAppInstanceIdSource.kt

@@ -0,0 +1,73 @@
+package io.advenue.plugin
+
+import android.content.Context
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * The Firebase App Instance ID source for React Native, by reflection.
+ *
+ * The class name and package are not incidental — they are the contract. The
+ * Android SDK resolves its enrichment plugins with `Class.forName` against the
+ * fixed names in `PluginRegistry`, so this file exists at exactly the name that
+ * lookup asks for. Rename it and the SDK stops finding it, silently.
+ *
+ * The monorepo's `plugin-firebase` artifact does the same job with ordinary
+ * typed code, and that is the better implementation — but it declares a compile
+ * dependency on `firebase-analytics`, and adding that here would force Firebase
+ * on every React Native app that installs this package. So this one is checked
+ * in rather than vendored, and reaches Firebase only if the host app already
+ * ships it.
+ *
+ * Every failure is best-effort null: Firebase absent, not initialised,
+ * analytics collection disabled, or simply slower than the deadline. The
+ * install goes out without the id rather than waiting for it.
+ */
+public class FirebaseAppInstanceIdSource : AppInstanceIdSource {
+  override fun read(context: Context, timeoutMs: Long): String? {
+    return try {
+      val ctx = context.applicationContext
+      val analyticsClass = Class.forName("com.google.firebase.analytics.FirebaseAnalytics")
+      val analytics =
+        analyticsClass.getMethod("getInstance", Context::class.java).invoke(null, ctx)
+      val task = analyticsClass.getMethod("getAppInstanceId").invoke(analytics)
+
+      val taskClass = Class.forName("com.google.android.gms.tasks.Task")
+      val listenerClass = Class.forName("com.google.android.gms.tasks.OnCompleteListener")
+      val result = AtomicReference<String?>(null)
+      val done = CountDownLatch(1)
+
+      val listener =
+        java.lang.reflect.Proxy.newProxyInstance(
+          listenerClass.classLoader,
+          arrayOf(listenerClass),
+        ) { _, method, args ->
+          if (method.name == "onComplete") {
+            try {
+              val completed = args?.firstOrNull()
+              val ok =
+                completed != null && taskClass.getMethod("isSuccessful").invoke(completed) == true
+              if (ok) {
+                result.set(taskClass.getMethod("getResult").invoke(completed) as? String)
+              }
+            } catch (_: Throwable) {
+              // Best effort; the latch still counts down below.
+            } finally {
+              done.countDown()
+            }
+          }
+          null
+        }
+
+      taskClass.getMethod("addOnCompleteListener", listenerClass).invoke(task, listener)
+      // The caller already runs this on the enrichment pool behind its own
+      // deadline; blocking here is what turns Firebase's callback into the
+      // synchronous answer the contract asks for.
+      done.await(timeoutMs, TimeUnit.MILLISECONDS)
+      result.get()?.takeIf { it.isNotEmpty() }
+    } catch (_: Throwable) {
+      null
+    }
+  }
+}

package/android/src/main/kotlin/io/advenue/plugin/PlayAdvertisingIdSource.kt

@@ -0,0 +1,47 @@
+package io.advenue.plugin
+
+import android.content.Context
+import com.google.android.gms.ads.identifier.AdvertisingIdClient
+import com.google.android.gms.appset.AppSet
+import com.google.android.gms.tasks.Tasks
+import java.util.concurrent.TimeUnit
+
+/**
+ * GAID and App Set ID.
+ *
+ * Adding this artifact merges `com.google.android.gms.permission.AD_ID` into the
+ * consumer's manifest. That is required for GAID access when targeting API 33+,
+ * **and** it changes the app's Play Console Data Safety declaration, and apps in
+ * the kids category must remove it. The integration docs carry the
+ * `tools:node="remove"` recipe — the consequence is the consumer's to accept,
+ * not ours to hide.
+ */
+public class PlayAdvertisingIdSource : AdvertisingIdSource {
+  override fun read(context: Context): AdvertisingId? {
+    val app = context.applicationContext
+
+    // Blocking by contract; the caller runs this off the main thread, where
+    // Play Services would throw.
+    val info = runCatching { AdvertisingIdClient.getAdvertisingIdInfo(app) }.getOrNull()
+
+    val raw = info?.id
+    // The all-zero GAID is what Play returns when tracking is limited. It looks
+    // like an identifier and is not one, so it must never travel.
+    val gaid = if (raw.isNullOrEmpty() || raw == ZERO_GAID) null else raw
+
+    val appSetId =
+      runCatching { Tasks.await(AppSet.getClient(app).appSetIdInfo, 2, TimeUnit.SECONDS).id }
+        .getOrNull()
+
+    if (gaid == null && appSetId == null && info == null) return null
+    return AdvertisingId(
+      gaid = gaid,
+      limitAdTracking = info?.isLimitAdTrackingEnabled ?: false,
+      appSetId = appSetId,
+    )
+  }
+
+  private companion object {
+    private const val ZERO_GAID = "00000000-0000-0000-0000-000000000000"
+  }
+}

package/android/src/main/kotlin/io/advenue/plugin/PlayInstallReferrerSource.kt

@@ -0,0 +1,85 @@
+package io.advenue.plugin
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import com.android.installreferrer.api.InstallReferrerClient
+import com.android.installreferrer.api.InstallReferrerStateListener
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Google Play Install Referrer.
+ *
+ * This is the deterministic attribution on Android: an install sent without it
+ * is an organic install. Which is why the caller waits for it, unlike iOS where
+ * waiting for ATT is wrong.
+ *
+ * The Play callback can fire setup-finished, disconnect, or never respond at all
+ * on an offline device. It must settle **exactly once** on every path and the
+ * service binding must be released on every path — a disconnect or a hung
+ * connection otherwise leaks the binding and hangs the install forever. The
+ * React Native module got this right with an AtomicBoolean; this keeps it.
+ */
+public class PlayInstallReferrerSource : InstallReferrerSource {
+  override fun read(context: Context, timeoutMs: Long): ReferrerResult? {
+    val app = context.applicationContext
+    val client = InstallReferrerClient.newBuilder(app).build()
+    val settled = AtomicBoolean(false)
+    val result = AtomicReference<ReferrerResult?>(null)
+    val done = CountDownLatch(1)
+    val handler = Handler(Looper.getMainLooper())
+
+    fun finish(value: ReferrerResult?) {
+      if (!settled.compareAndSet(false, true)) return
+      result.set(value)
+      runCatching { client.endConnection() }
+      done.countDown()
+    }
+
+    // Watchdog: the service may never call back. The referrer is best-effort
+    // enrichment, so the caller must always be released.
+    handler.postDelayed({ finish(null) }, timeoutMs)
+
+    runCatching {
+      client.startConnection(
+        object : InstallReferrerStateListener {
+          override fun onInstallReferrerSetupFinished(responseCode: Int) {
+            if (responseCode != InstallReferrerClient.InstallReferrerResponse.OK) {
+              finish(null)
+              return
+            }
+            val value =
+              runCatching {
+                val details = client.installReferrer
+                ReferrerResult(
+                  referrer = details.installReferrer,
+                  clickTimestamp = details.referrerClickTimestampSeconds,
+                  installTimestamp = details.installBeginTimestampSeconds,
+                  // Play returns 0 here when the install is unverified; the
+                  // caller forwards these as server-trusted only when non-zero.
+                  clickServerTimestamp = details.referrerClickTimestampServerSeconds,
+                  installServerTimestamp = details.installBeginTimestampServerSeconds,
+                  googlePlayInstant = details.googlePlayInstantParam,
+                )
+              }
+                .getOrNull()
+            finish(value)
+          }
+
+          override fun onInstallReferrerServiceDisconnected() {
+            // Dropped before setup finished, e.g. under memory pressure.
+            finish(null)
+          }
+        },
+      )
+    }
+      .onFailure { finish(null) }
+
+    done.await(timeoutMs + 500, TimeUnit.MILLISECONDS)
+    handler.removeCallbacksAndMessages(null)
+    return result.get()
+  }
+}