@advenue/react-native 0.9.0 → 1.0.1

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()
+  }
+}

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

@@ -0,0 +1,86 @@
+package io.advenue.plugin
+
+import android.content.Context
+import android.content.pm.PackageManager
+import com.google.android.play.core.integrity.IntegrityManagerFactory
+import com.google.android.play.core.integrity.StandardIntegrityManager.PrepareIntegrityTokenRequest
+import com.google.android.play.core.integrity.StandardIntegrityManager.StandardIntegrityTokenProvider
+import com.google.android.play.core.integrity.StandardIntegrityManager.StandardIntegrityTokenRequest
+import com.google.android.gms.tasks.Tasks
+import java.util.concurrent.TimeUnit
+
+/**
+ * Play Integrity Standard API — device attestation.
+ *
+ * The token provider is warmed once, because preparing it is the slow half and
+ * doing it per request would put seconds on the install path.
+ *
+ * The Google Cloud project number comes from the app's manifest:
+ * ```xml
+ * <meta-data android:name="io.advenue.INTEGRITY_CLOUD_PROJECT_NUMBER"
+ *            android:value="123456789012" />
+ * ```
+ * Read as a long **and** as a string, because Android stores a large
+ * `android:value` as a String — reading only one of the two makes the feature
+ * silently unavailable for most projects.
+ */
+public class PlayIntegritySource : AttestationSource {
+  @Volatile private var provider: StandardIntegrityTokenProvider? = null
+  @Volatile private var warmed = false
+
+  override fun token(context: Context, requestHash: String): String? {
+    val app = context.applicationContext
+    warm(app)
+    val provider = this.provider ?: return null
+
+    return runCatching {
+      Tasks.await(
+          provider.request(
+            StandardIntegrityTokenRequest.builder().setRequestHash(requestHash).build(),
+          ),
+          10,
+          TimeUnit.SECONDS,
+        )
+        .token()
+    }
+      .getOrNull()
+  }
+
+  private fun warm(context: Context) {
+    if (warmed) return
+    warmed = true
+    val projectNumber = cloudProjectNumber(context)
+    // Zero means the app never configured it — a different situation from Play
+    // Integrity being unavailable, and the two need different answers from
+    // support. Neither is an error here: attestation is best-effort and the
+    // install proceeds without it.
+    if (projectNumber == 0L) return
+
+    runCatching {
+      val manager = IntegrityManagerFactory.createStandard(context)
+      provider =
+        Tasks.await(
+          manager.prepareIntegrityToken(
+            PrepareIntegrityTokenRequest.builder().setCloudProjectNumber(projectNumber).build(),
+          ),
+          15,
+          TimeUnit.SECONDS,
+        )
+    }
+  }
+
+  private fun cloudProjectNumber(context: Context): Long =
+    runCatching {
+      val info =
+        context.packageManager.getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+      val meta = info.metaData ?: return 0L
+      meta.getLong(META_KEY, 0L).takeIf { it != 0L }
+        ?: meta.getString(META_KEY)?.toLongOrNull()
+        ?: 0L
+    }
+      .getOrDefault(0L)
+
+  private companion object {
+    private const val META_KEY = "io.advenue.INTEGRITY_CLOUD_PROJECT_NUMBER"
+  }
+}

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

@@ -0,0 +1,61 @@
+package io.advenue.plugin
+
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Resolves a plugin's entry class by fixed name, once, at initialisation.
+ *
+ * The consumer adds a Gradle line and writes nothing else, which is how Adjust's
+ * ten plugins work — `sdk-core/src/main/java/com/adjust/sdk/Reflection.java`
+ * resolves them the same way.
+ *
+ * **This is not the rejected "compileOnly plus reflection" shape.** There,
+ * reflection wrapped every vendor API call and every one of them was untyped.
+ * Here there is one lookup of *our own* class, at init, and the resolved class
+ * then talks to its dependency with ordinary compile-time typing.
+ *
+ * **ServiceLoader was considered and rejected.** It is the JVM standard and R8
+ * understands it, but its registration lives in a `META-INF/services` resource,
+ * which jar merging and aggressive shrinkers drop silently. A silently absent
+ * referrer plugin is an attribution outage that looks like organic traffic — the
+ * worst failure shape available. A missing class is detectable, and one
+ * `consumerProguardFiles` rule keeps it.
+ */
+public object PluginRegistry {
+  public const val PLAY_REFERRER: String = "io.advenue.plugin.PlayInstallReferrerSource"
+  public const val PLAY_IDENTITY: String = "io.advenue.plugin.PlayAdvertisingIdSource"
+  public const val PLAY_INTEGRITY: String = "io.advenue.plugin.PlayIntegritySource"
+  public const val FIREBASE: String = "io.advenue.plugin.FirebaseAppInstanceIdSource"
+
+  private val cache = ConcurrentHashMap<String, Any>()
+
+  /**
+   * The plugin at [className], or null when the artifact is not on the
+   * classpath — which is the ordinary case, not an error.
+   *
+   * A class that exists but does not implement the contract is a packaging
+   * mistake, and it degrades to "no plugin" rather than taking the host app
+   * down: an SDK that throws during `initialize` crashes an app that merely
+   * mis-declared a dependency.
+   */
+  @Suppress("UNCHECKED_CAST")
+  public inline fun <reified T : Any> load(className: String): T? = loadAs(className, T::class.java)
+
+  @PublishedApi
+  internal fun <T : Any> loadAs(className: String, type: Class<T>): T? {
+    cache[className]?.let { return if (type.isInstance(it)) type.cast(it) else null }
+    return try {
+      val loaded = Class.forName(className).getDeclaredConstructor().newInstance()
+      if (!type.isInstance(loaded)) return null
+      cache[className] = loaded
+      type.cast(loaded)
+    } catch (_: Throwable) {
+      null
+    }
+  }
+
+  /** Test surface: forget what was resolved, so a test can vary the classpath. */
+  internal fun reset() {
+    cache.clear()
+  }
+}