@advenue/react-native 0.8.0 → 1.0.0

package/android/src/main/kotlin/io/advenue/core/Time.kt

@@ -0,0 +1,56 @@
+package io.advenue.core
+
+/**
+ * Milliseconds since the epoch to the exact form TypeScript's `toISOString()`
+ * produces: always three fractional digits, always `Z`.
+ *
+ * Computed arithmetically rather than with `Calendar` or `SimpleDateFormat`.
+ * `SimpleDateFormat` is not thread-safe, `java.time` needs API 26, and both
+ * would make the function depend on a default locale and time zone that a host
+ * app can change underneath us. Every event on the wire carries this value, so
+ * it has to be a pure function of its input.
+ */
+internal fun iso8601(ms: Long): String {
+  // Floor to the second first, so a negative millisecond remainder cannot
+  // borrow from the second field for pre-epoch timestamps.
+  val wholeSeconds = Math.floorDiv(ms, 1000L)
+  val millis = ms - wholeSeconds * 1000L
+
+  val days = Math.floorDiv(wholeSeconds, 86_400L)
+  var secondOfDay = wholeSeconds - days * 86_400L
+  val hour = secondOfDay / 3600
+  secondOfDay -= hour * 3600
+  val minute = secondOfDay / 60
+  val second = secondOfDay - minute * 60
+
+  val (year, month, day) = civilFromDays(days)
+  return String.format(
+    "%04d-%02d-%02dT%02d:%02d:%02d.%03dZ",
+    year,
+    month,
+    day,
+    hour,
+    minute,
+    second,
+    millis,
+  )
+}
+
+/**
+ * Days since 1970-01-01 to a proleptic Gregorian year/month/day. Hinnant's
+ * civil-from-days: exact for the whole range a Long of milliseconds can hold,
+ * and free of any calendar object.
+ */
+private fun civilFromDays(daysSinceEpoch: Long): Triple<Long, Long, Long> {
+  val z = daysSinceEpoch + 719_468L
+  val era = Math.floorDiv(z, 146_097L)
+  val dayOfEra = z - era * 146_097L
+  val yearOfEra =
+    (dayOfEra - dayOfEra / 1460 + dayOfEra / 36_524 - dayOfEra / 146_096) / 365
+  val year = yearOfEra + era * 400
+  val dayOfYear = dayOfEra - (365 * yearOfEra + yearOfEra / 4 - yearOfEra / 100)
+  val monthPrime = (5 * dayOfYear + 2) / 153
+  val day = dayOfYear - (153 * monthPrime + 2) / 5 + 1
+  val month = if (monthPrime < 10) monthPrime + 3 else monthPrime - 9
+  return Triple(if (month <= 2) year + 1 else year, month, day)
+}

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

@@ -0,0 +1,149 @@
+package io.advenue.platform
+
+import android.content.Context
+import android.net.Uri
+import android.os.Build
+import android.os.StatFs
+import android.telephony.TelephonyManager
+import java.util.Locale
+import java.util.TimeZone
+
+/**
+ * Meta (Facebook/Instagram) install referrer, read from the installed Meta app's
+ * content provider. No dependency, which is why it lives in the base rather than
+ * a plugin.
+ *
+ * Two details are easy to get wrong and both come from Meta's own MIR
+ * documentation: Instagram's authority is `com.instagram.contentprovider.*`,
+ * **not** `<package>.provider.*` like the others, and the path segment is the
+ * **Meta app id**, not the Android package name.
+ *
+ * Returns null when no Meta app is installed, which is the common case.
+ */
+internal fun readMetaInstallReferrer(context: Context, fbAppId: String): Map<String, Any?>? {
+  val providers =
+    listOf(
+      "com.facebook.katana" to "com.facebook.katana.provider.InstallReferrerProvider",
+      "com.instagram.android" to "com.instagram.contentprovider.InstallReferrerProvider",
+      "com.facebook.lite" to "com.facebook.lite.provider.InstallReferrerProvider",
+    )
+
+  for ((pkg, authority) in providers) {
+    val uri = Uri.parse("content://$authority/$fbAppId")
+    val cursor =
+      runCatching {
+        context.contentResolver.query(
+          uri,
+          arrayOf("install_referrer", "is_ct", "actual_timestamp"),
+          null,
+          null,
+          null,
+        )
+      }
+        .getOrNull() ?: continue
+
+    cursor.use {
+      if (it.moveToFirst()) {
+        val referrerIdx = it.getColumnIndex("install_referrer")
+        if (referrerIdx >= 0) {
+          val ctIdx = it.getColumnIndex("is_ct")
+          val tsIdx = it.getColumnIndex("actual_timestamp")
+          return mapOf(
+            "installReferrer" to it.getString(referrerIdx),
+            "isClickThrough" to (ctIdx >= 0 && it.getInt(ctIdx) == 1),
+            "actualTimestamp" to if (tsIdx >= 0) it.getLong(tsIdx) else 0L,
+            "provider" to pkg,
+          )
+        }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * IAB TCF v2 data a compliant CMP writes to the **default**
+ * `"<package>_preferences"` file, per the TCF spec — deliberately not our own
+ * suite. Reading our file instead would report no consent data for every app on
+ * earth, silently.
+ */
+internal fun readTcf(context: Context): Map<String, Any?>? {
+  val prefs =
+    runCatching {
+      context.getSharedPreferences("${context.packageName}_preferences", Context.MODE_PRIVATE)
+    }
+      .getOrNull() ?: return null
+
+  // prefs.all plus a map lookup: a missing key reads as null with no default
+  // involved, so "missing" and "0" stay distinguishable. `as? Number` tolerates
+  // a CMP writing Int OR Long — SharedPreferences has no fixed numeric type and
+  // the TCF spec does not pick one.
+  val gdprApplies = runCatching { (prefs.all["IABTCF_gdprApplies"] as? Number)?.toInt() }.getOrNull()
+  val purposeConsents =
+    runCatching { prefs.getString("IABTCF_PurposeConsents", null) }.getOrNull()
+
+  return tcfFrom(gdprApplies, purposeConsents)
+}
+
+/**
+ * The pure half, so the distinction that matters is testable without a Context:
+ * a CMP that has never written `IABTCF_gdprApplies` is not the same as one that
+ * wrote zero, and treating them alike would apply GDPR gating to users it does
+ * not cover, or fail to apply it to users it does.
+ */
+internal fun tcfFrom(gdprApplies: Int?, purposeConsents: String?): Map<String, Any?>? {
+  if (gdprApplies == null && purposeConsents == null) return null
+  return mapOf("gdprApplies" to gdprApplies, "purposeConsents" to purposeConsents)
+}
+
+/**
+ * Device metadata for Meta CAPI `extinfo`.
+ *
+ * Best-effort per field: a field is **omitted**, never defaulted, when its
+ * source is unavailable — a misleading zero is worse than a missing value,
+ * because downstream it is indistinguishable from a real measurement.
+ */
+internal fun collectDeviceInfo(context: Context): Map<String, Any?> {
+  val map = LinkedHashMap<String, Any?>()
+  map["model"] = Build.MODEL
+  map["locale"] = Locale.getDefault().toString()
+  map["timezone"] = TimeZone.getDefault().id
+  map["cpuCores"] = Runtime.getRuntime().availableProcessors()
+  map["packageName"] = context.packageName
+
+  runCatching {
+    @Suppress("DEPRECATION")
+    val info = context.packageManager.getPackageInfo(context.packageName, 0)
+    info.versionName?.let { map["shortVersion"] = it }
+    val code =
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+        info.longVersionCode
+      } else {
+        @Suppress("DEPRECATION") info.versionCode.toLong()
+      }
+    map["longVersion"] = code.toString()
+  }
+
+  runCatching {
+    val metrics = context.resources.displayMetrics
+    map["screenWidth"] = metrics.widthPixels
+    map["screenHeight"] = metrics.heightPixels
+    map["screenDensity"] = metrics.density.toDouble()
+  }
+
+  runCatching {
+    val stat = StatFs(context.filesDir.path)
+    val gb = 1024.0 * 1024.0 * 1024.0
+    map["totalStorageGb"] = (stat.blockCountLong * stat.blockSizeLong).toDouble() / gb
+    map["freeStorageGb"] = (stat.availableBlocksLong * stat.blockSizeLong).toDouble() / gb
+  }
+
+  runCatching {
+    val carrier =
+      (context.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager)
+        ?.networkOperatorName
+    if (!carrier.isNullOrEmpty()) map["carrier"] = carrier
+  }
+
+  return map
+}

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

@@ -0,0 +1,33 @@
+package io.advenue.platform
+
+import io.advenue.core.KeyValueStore
+
+/**
+ * Routes the three install-scoped keys to [InstallScopedStore] and everything
+ * else to [PreferencesStore].
+ *
+ * The engine writes `install_sent` through the ordinary `KeyValueStore`
+ * interface — it has no business knowing which Android directory a key belongs
+ * in. Without this router that write lands in SharedPreferences, which Auto
+ * Backup restores into a reinstall, and that installation's install event never
+ * fires again. The RN module solved it the same way, with an
+ * `isInstallScopedKey` check at the storage boundary.
+ */
+internal class CompositeStore(
+  private val preferences: PreferencesStore,
+  private val scoped: InstallScopedStore,
+) : KeyValueStore {
+
+  override fun getString(key: String): String? =
+    if (isScoped(key)) scoped.get(key) else preferences.getString(key)
+
+  override fun setString(key: String, value: String) {
+    if (isScoped(key)) scoped.set(key, value) else preferences.setString(key, value)
+  }
+
+  override fun remove(key: String) {
+    if (isScoped(key)) scoped.remove(key) else preferences.remove(key)
+  }
+
+  private fun isScoped(key: String) = key in InstallScopedStore.INSTALL_SCOPED_KEYS
+}

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

@@ -0,0 +1,68 @@
+package io.advenue.platform
+
+import io.advenue.core.ConversionFetcher
+import io.advenue.core.ConversionResult
+import io.advenue.core.DeepLink
+import io.advenue.core.IngestError
+import io.advenue.core.parseJson
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import java.net.URLEncoder
+
+/**
+ * Asks the server what this device was attributed to.
+ *
+ * A `pending` answer means the pipeline has not decided yet. Most devices are
+ * organic and answer pending forever, which is why the caller has a budget
+ * rather than a loop.
+ */
+public class HttpConversionFetcher(
+  private val endpoint: String = DEFAULT_ENDPOINT,
+  private val apiKey: String,
+  private val deviceId: String,
+  private val timeoutMs: Int = 15_000,
+) : ConversionFetcher {
+
+  override fun fetch(): ConversionResult {
+    val escaped = URLEncoder.encode(deviceId, "UTF-8")
+    val connection =
+      URL("$endpoint/sdk/conversion-data?deviceId=$escaped").openConnection()
+        as HttpURLConnection
+    try {
+      connection.requestMethod = "GET"
+      connection.connectTimeout = timeoutMs
+      connection.readTimeout = timeoutMs
+      connection.setRequestProperty("x-api-key", apiKey)
+
+      val status =
+        try {
+          connection.responseCode
+        } catch (_: IOException) {
+          // No status to reason about; 408 marks it retryable, as sdk-core does.
+          throw IngestError(408)
+        }
+      if (status < 200 || status >= 300) throw IngestError(status)
+
+      val body =
+        parseJson(connection.inputStream.use { it.readBytes() }.toString(Charsets.UTF_8))
+          as? Map<*, *> ?: return ConversionResult.Pending
+      if (body["pending"] == true) return ConversionResult.Pending
+
+      return ConversionResult.Resolved(
+        DeepLink(
+          deepLinkValue = body["deepLinkValue"] as? String,
+          campaign = body["campaign"] as? String,
+          network = body["network"] as? String,
+          influencerId = body["influencerId"] as? String,
+        ),
+      )
+    } catch (error: IngestError) {
+      throw error
+    } catch (_: IOException) {
+      throw IngestError(408)
+    } finally {
+      connection.disconnect()
+    }
+  }
+}

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