@advenue/react-native 0.9.0 → 1.0.1

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

@@ -0,0 +1,189 @@
+package io.advenue.core
+
+internal const val SESSION_STATE_KEY: String = "advenue.session"
+
+/** 30 minutes. */
+internal const val DEFAULT_SESSION_WINDOW_MS: Long = 1_800_000L
+
+/** A session lifecycle event, wrapped by the engine as a `type: "session"` event. */
+internal data class SessionEvent(val name: String, val properties: Map<String, Any?>)
+
+private data class SessionState(
+  val sessionId: String,
+  val sessionNumber: Long,
+  val lastBackgroundAt: Long?,
+  val subSessionCount: Long,
+  val activeStart: Long?,
+  val firstForegroundAt: Long,
+  val timeSpentMs: Long,
+) {
+  /**
+   * The persisted blob. Field names are frozen: a rename would make RN-written
+   * state unloadable and silently restart every device's session numbering.
+   */
+  fun toMap(): Map<String, Any?> =
+    mapOf(
+      "sessionId" to sessionId,
+      "sessionNumber" to sessionNumber,
+      "lastBackgroundAt" to lastBackgroundAt,
+      "subSessionCount" to subSessionCount,
+      "activeStart" to activeStart,
+      "firstForegroundAt" to firstForegroundAt,
+      "timeSpentMs" to timeSpentMs,
+    )
+}
+
+/**
+ * Platform-agnostic session state machine. Pure: it persists state and returns
+ * the events to emit; enqueueing is the caller's job. Driven by foreground and
+ * background lifecycle signals.
+ */
+internal class SessionTracker(
+  private val store: KeyValueStore,
+  private val clock: Clock,
+  private val windowMs: Long = DEFAULT_SESSION_WINDOW_MS,
+  private val uuid: UuidSource,
+) {
+  private var lastState: SessionState? = null
+
+  /** Drops the cached state (erasure) so a wiped store cannot be resurrected. */
+  public fun reset() {
+    lastState = null
+  }
+
+  /**
+   * Foreground transition, including cold start. Returns:
+   * - empty — a sub-session inside the window;
+   * - `[session_start]` — a new session;
+   * - `[session_end, session_start]` — kill recovery: the prior session was
+   *   still open when the OS killed the app, so its end is synthesised first.
+   */
+  public fun handleForeground(): List<SessionEvent> {
+    val state = load()
+    val now = clock.nowMs()
+    val gap = if (state?.lastBackgroundAt != null) now - state.lastBackgroundAt else null
+
+    if (state == null || gap == null || gap >= windowMs) {
+      val sessionNumber = (state?.sessionNumber ?: 0L) + 1L
+      val sessionId = uuid.next()
+      save(
+        SessionState(
+          sessionId = sessionId,
+          sessionNumber = sessionNumber,
+          lastBackgroundAt = null,
+          subSessionCount = 1L,
+          activeStart = now,
+          firstForegroundAt = now,
+          timeSpentMs = 0L,
+        ),
+      )
+
+      val sessionStart =
+        SessionEvent(
+          "session_start",
+          mapOf(
+            "sessionId" to sessionId,
+            "sessionNumber" to sessionNumber,
+            "subSession" to 1L,
+            "isFirstSession" to (sessionNumber == 1L),
+            // 0 rather than infinity, which would not survive JSON.
+            "timeSinceLastSessionMs" to (gap ?: 0L),
+          ),
+        )
+
+      if (state?.activeStart != null) {
+        val killTime = state.lastBackgroundAt ?: now
+        val activeMs = Math.max(0L, killTime - state.activeStart)
+        val timeSpentMs = state.timeSpentMs + activeMs
+        val sessionEnd =
+          SessionEvent(
+            "session_end",
+            mapOf(
+              "sessionId" to state.sessionId,
+              "sessionNumber" to state.sessionNumber,
+              "subSession" to state.subSessionCount,
+              "activeMs" to activeMs,
+              "timeSpentMs" to timeSpentMs,
+              "sessionLengthMs" to Math.max(0L, killTime - state.firstForegroundAt),
+              "synthetic" to true,
+            ),
+          )
+        return listOf(sessionEnd, sessionStart)
+      }
+
+      return listOf(sessionStart)
+    }
+
+    save(state.copy(subSessionCount = state.subSessionCount + 1L, activeStart = now))
+    return emptyList()
+  }
+
+  /** Background transition. Returns a session_end with the active duration, or null. */
+  public fun handleBackground(): SessionEvent? {
+    val state = load() ?: return null
+    val activeStart = state.activeStart ?: return null
+    val now = clock.nowMs()
+    val activeMs = Math.max(0L, now - activeStart)
+    val timeSpentMs = state.timeSpentMs + activeMs
+    save(state.copy(lastBackgroundAt = now, activeStart = null, timeSpentMs = timeSpentMs))
+    return SessionEvent(
+      "session_end",
+      mapOf(
+        "sessionId" to state.sessionId,
+        "sessionNumber" to state.sessionNumber,
+        "subSession" to state.subSessionCount,
+        // This sub-session's foreground stretch.
+        "activeMs" to activeMs,
+        // Cumulative active time across the session's sub-sessions.
+        "timeSpentMs" to timeSpentMs,
+        // Wall-clock span.
+        "sessionLengthMs" to Math.max(0L, now - state.firstForegroundAt),
+      ),
+    )
+  }
+
+  private fun load(): SessionState? {
+    lastState?.let { return it }
+    val raw = store.getString(SESSION_STATE_KEY) ?: return null
+    val map = parseJson(raw) as? Map<*, *> ?: return null
+
+    val sessionId = map["sessionId"] as? String ?: return null
+    val sessionNumber = (map["sessionNumber"] as? Number)?.toLong() ?: return null
+    val subSessionCount = (map["subSessionCount"] as? Number)?.toLong() ?: return null
+    val lastBackgroundAt = (map["lastBackgroundAt"] as? Number)?.toLong()
+    val activeStart = (map["activeStart"] as? Number)?.toLong()
+
+    // Back-compat for state persisted before these two fields existed. Without
+    // it, an app updating from an older SDK would fail to load its own session
+    // and restart its numbering.
+    val timeSpentMs = (map["timeSpentMs"] as? Number)?.toLong() ?: 0L
+    val firstForegroundAt =
+      (map["firstForegroundAt"] as? Number)?.toLong()
+        ?: activeStart
+        ?: lastBackgroundAt
+        ?: clock.nowMs()
+
+    val state =
+      SessionState(
+        sessionId = sessionId,
+        sessionNumber = sessionNumber,
+        lastBackgroundAt = lastBackgroundAt,
+        subSessionCount = subSessionCount,
+        activeStart = activeStart,
+        firstForegroundAt = firstForegroundAt,
+        timeSpentMs = timeSpentMs,
+      )
+    lastState = state
+    return state
+  }
+
+  private fun save(state: SessionState) {
+    lastState = state
+    try {
+      store.setString(SESSION_STATE_KEY, writeCanonicalJson(state.toMap()))
+    } catch (_: Exception) {
+      // The in-memory state keeps this process consistent even if the write
+      // failed; losing session continuity is better than crashing the host app.
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+package io.advenue.core
+
+import java.util.Timer
+import java.util.TimerTask
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+/** Wall clock. */
+internal class SystemClock : Clock {
+  override fun nowMs(): Long = System.currentTimeMillis()
+}
+
+/** Random v4 identifiers, lowercase, matching what TypeScript's generator emits. */
+internal class SystemUuids : UuidSource {
+  override fun next(): String = UUID.randomUUID().toString()
+}
+
+/**
+ * Deferred execution for the queue's persist debounce.
+ *
+ * **Isolation contract.** The scheduled work touches the event list, which is
+ * confined to the engine's thread. Running it on the timer thread would race
+ * `enqueue` — an iteration over an `ArrayList` while another thread appends —
+ * so the timer only *wakes*, and [dispatcher] hops the work back onto the
+ * engine's thread. The Swift port put the same requirement on its `Scheduler`
+ * protocol for exactly this reason.
+ *
+ * [dispatcher] is assigned after the pipe exists. Until then it runs inline,
+ * which is safe because nothing can be enqueued before the pipe exists, so no
+ * persist can have been scheduled.
+ */
+internal class TimerScheduler : Scheduler {
+  private val timer = Timer("advenue-scheduler", true)
+  private val tasks = ConcurrentHashMap<CancelToken, TimerTask>()
+  private val next = AtomicLong(1)
+
+  @Volatile public var dispatcher: ((() -> Unit) -> Unit)? = null
+
+  override fun schedule(afterMs: Int, work: () -> Unit): CancelToken {
+    val token = next.getAndIncrement()
+    val task =
+      object : TimerTask() {
+        override fun run() {
+          tasks.remove(token)
+          val hop = dispatcher
+          if (hop != null) hop(work) else work()
+        }
+      }
+    tasks[token] = task
+    timer.schedule(task, afterMs.toLong())
+    return token
+  }
+
+  override fun cancel(token: CancelToken) {
+    tasks.remove(token)?.cancel()
+  }
+}

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

@@ -0,0 +1,48 @@
+package io.advenue.core
+
+/**
+ * Maps raw IAB TCF v2 CMP data to the DMA [Consent] shape, per Google's EU User
+ * Consent Policy reading of the TCF purposes:
+ *
+ * - `ad_storage` ← Purpose 1
+ * - `ad_user_data` ← Purposes 1 **and** 7
+ * - `ad_personalization` ← Purposes 3 **and** 4
+ *
+ * Returns null when `gdprApplies` is neither 0 nor 1. Absent consent must stay
+ * absent: a guessed value is forwarded to ad networks as a real signal, and a
+ * signal invented on a user's behalf is the one thing consent plumbing must
+ * never do.
+ */
+internal fun tcfToConsent(gdprApplies: Int?, purposeConsents: String?): Consent? {
+  if (gdprApplies != 0 && gdprApplies != 1) return null
+  if (gdprApplies == 0) return Consent(isUserSubjectToGDPR = false)
+
+  val consents = purposeConsents ?: ""
+  fun purpose(n: Int): Boolean = consents.getOrNull(n - 1) == '1'
+
+  return Consent(
+    isUserSubjectToGDPR = true,
+    hasConsentForAdStorage = purpose(1),
+    hasConsentForDataUsage = purpose(1) && purpose(7),
+    hasConsentForAdsPersonalization = purpose(3) && purpose(4),
+  )
+}
+
+/**
+ * Meta AEM `campaign_ids`, extracted from an `al_applink_data` payload.
+ *
+ * The input is the ALREADY percent-decoded query value: decoding again would
+ * corrupt a blob containing '%'. Meta does not publicly document the schema, so
+ * both shapes seen in the wild are accepted, top level first.
+ *
+ * The blob is opaque, Meta-encrypted, non-user metadata and is returned
+ * verbatim — never trimmed or re-encoded. The 2048 cap is URL hygiene; the
+ * server re-validates, because an SDK-side cap is advisory at a trust boundary.
+ */
+internal fun extractAemCampaignIds(alApplinkData: String): String? {
+  val parsed = parseJson(alApplinkData) as? Map<*, *> ?: return null
+  val top = parsed["campaign_ids"] as? String
+  val nested = (parsed["extras"] as? Map<*, *>)?.get("campaign_ids") as? String
+  val value = top?.takeIf { it.isNotEmpty() } ?: nested?.takeIf { it.isNotEmpty() } ?: return null
+  return value.takeIf { it.length <= 2048 }
+}

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,163 @@
+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.
+ */
+/**
+ * The app's own version (`versionName`) for every event's top-level
+ * `appVersion`. Resolved here, never taken from the app: the React Native 0.x
+ * layer filled it this way, and 1.0 relying on the config instead left every
+ * event unversioned (2026-09-19). Null when the package manager can't answer.
+ */
+internal fun readAppVersion(context: Context): String? =
+  runCatching {
+      @Suppress("DEPRECATION")
+      context.packageManager.getPackageInfo(context.packageName, 0).versionName
+    }
+    .getOrNull()
+    ?.takeIf { it.isNotBlank() }
+
+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()
+    }
+  }
+}