@advenue/react-native 0.8.0 → 1.0.0

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

@@ -0,0 +1,272 @@
+package io.advenue.core
+
+/**
+ * Canonical JSON, written by hand.
+ *
+ * Three reasons, each sufficient on its own. `org.json` is a stub in JVM unit
+ * tests — calling it throws unless the test is mocked or run under Robolectric.
+ * Gson, Moshi and kotlinx.serialization are each a dependency an SDK would push
+ * into the host app's version resolution, and kotlinx.serialization is also a
+ * compiler plugin. And none of the three guarantees key order, which the
+ * byte-exact `envelope/` conformance vectors require.
+ *
+ * A fourth reason emerged from writing it: no reflection, so consumers need no
+ * `keep` rules for model classes. Gson or Moshi would push those rules into
+ * every consumer's build.
+ */
+
+/**
+ * Serialises [value] with sorted object keys, omitting null object entries.
+ *
+ * Accepted types are String, Boolean, Int, Long, Double, List and Map with
+ * String keys. Anything else throws, rather than being coerced to something
+ * plausible: a silently mangled property is worse than a rejected event,
+ * because it reaches the warehouse looking correct.
+ */
+internal fun writeCanonicalJson(value: Any?): String {
+  val out = StringBuilder()
+  writeValue(value, out)
+  return out.toString()
+}
+
+private fun writeValue(value: Any?, out: StringBuilder) {
+  when (value) {
+    null -> out.append("null")
+    is String -> writeString(value, out)
+    is Boolean -> out.append(if (value) "true" else "false")
+    is Int -> out.append(value.toString())
+    is Long -> out.append(value.toString())
+    is Double -> out.append(formatDouble(value))
+    is Float -> out.append(formatDouble(value.toDouble()))
+    is Map<*, *> -> writeObject(value, out)
+    is List<*> -> {
+      out.append('[')
+      value.forEachIndexed { index, element ->
+        if (index > 0) out.append(',')
+        // A null inside an ARRAY has no key to omit, so it is serialised.
+        writeValue(element, out)
+      }
+      out.append(']')
+    }
+    else -> throw IllegalArgumentException(
+      "unencodable JSON value: ${value::class.java.simpleName}",
+    )
+  }
+}
+
+private fun writeObject(map: Map<*, *>, out: StringBuilder) {
+  out.append('{')
+  var first = true
+  // Sorted so output is byte-comparable with the conformance vectors and with
+  // what Swift's .sortedKeys and the TypeScript snapshots produce.
+  val keys = map.keys.map { it as? String ?: throw IllegalArgumentException("non-string JSON key") }
+  for (key in keys.sorted()) {
+    val entry = map[key]
+    // zod .optional() accepts a missing key and rejects an explicit null.
+    if (entry == null) continue
+    if (!first) out.append(',')
+    first = false
+    writeString(key, out)
+    out.append(':')
+    writeValue(entry, out)
+  }
+  out.append('}')
+}
+
+/**
+ * `JSON.stringify` prints an integral number without a decimal point: `1`, not
+ * `1.0`. Below 2^53 a double is exactly integral or it is not, so the check is
+ * safe; above it the plain representation is used, as JavaScript does.
+ */
+private fun formatDouble(value: Double): String {
+  if (!value.isFinite()) throw IllegalArgumentException("non-finite JSON number: $value")
+  if (value == Math.floor(value) && Math.abs(value) < 9_007_199_254_740_992.0) {
+    return value.toLong().toString()
+  }
+  return value.toString()
+}
+
+private fun writeString(value: String, out: StringBuilder) {
+  out.append('"')
+  for (char in value) {
+    when (char) {
+      '"' -> out.append("\\\"")
+      '\\' -> out.append("\\\\")
+      '\b' -> out.append("\\b")
+      '\n' -> out.append("\\n")
+      '\r' -> out.append("\\r")
+      '\t' -> out.append("\\t")
+      '\u000C' -> out.append("\\f")
+      // A forward slash is NOT escaped: JSON.stringify leaves it, and Swift is
+      // configured with .withoutEscapingSlashes to match.
+      else ->
+        if (char < ' ') {
+          out.append(String.format("\\u%04x", char.code))
+        } else {
+          out.append(char)
+        }
+    }
+  }
+  out.append('"')
+}
+
+/**
+ * Parses JSON into Map/List/String/Boolean/Long/Double/null.
+ *
+ * Returns null on malformed input rather than throwing. This only ever reads
+ * data the SDK itself wrote — the persisted queue and session blobs — plus one
+ * diagnostic field from an ingest response, and a corrupt blob must cost the
+ * offline buffer rather than brick the SDK on every launch.
+ */
+internal fun parseJson(text: String): Any? =
+  try {
+    val parser = JsonParser(text)
+    val value = parser.parseValue()
+    parser.skipWhitespace()
+    if (!parser.atEnd()) null else value
+  } catch (_: Exception) {
+    null
+  }
+
+private class JsonParser(private val text: String) {
+  private var index = 0
+
+  fun atEnd(): Boolean = index >= text.length
+
+  fun skipWhitespace() {
+    while (index < text.length && text[index].isWhitespace()) index++
+  }
+
+  fun parseValue(): Any? {
+    skipWhitespace()
+    if (atEnd()) throw IllegalStateException("unexpected end")
+    return when (text[index]) {
+      '{' -> parseObject()
+      '[' -> parseArray()
+      '"' -> parseString()
+      't' -> literal("true", true)
+      'f' -> literal("false", false)
+      'n' -> literal("null", null)
+      else -> parseNumber()
+    }
+  }
+
+  private fun literal(token: String, value: Any?): Any? {
+    if (!text.startsWith(token, index)) throw IllegalStateException("bad literal")
+    index += token.length
+    return value
+  }
+
+  private fun parseObject(): Map<String, Any?> {
+    index++ // {
+    val result = LinkedHashMap<String, Any?>()
+    skipWhitespace()
+    if (text[index] == '}') {
+      index++
+      return result
+    }
+    while (true) {
+      skipWhitespace()
+      val key = parseString()
+      skipWhitespace()
+      if (text[index] != ':') throw IllegalStateException("expected :")
+      index++
+      result[key] = parseValue()
+      skipWhitespace()
+      when (text[index]) {
+        ',' -> index++
+        '}' -> {
+          index++
+          return result
+        }
+        else -> throw IllegalStateException("expected , or }")
+      }
+    }
+  }
+
+  private fun parseArray(): List<Any?> {
+    index++ // [
+    val result = ArrayList<Any?>()
+    skipWhitespace()
+    if (text[index] == ']') {
+      index++
+      return result
+    }
+    while (true) {
+      result.add(parseValue())
+      skipWhitespace()
+      when (text[index]) {
+        ',' -> index++
+        ']' -> {
+          index++
+          return result
+        }
+        else -> throw IllegalStateException("expected , or ]")
+      }
+    }
+  }
+
+  private fun parseString(): String {
+    if (text[index] != '"') throw IllegalStateException("expected string")
+    index++
+    val out = StringBuilder()
+    while (true) {
+      val char = text[index]
+      when {
+        char == '"' -> {
+          index++
+          return out.toString()
+        }
+        char == '\\' -> {
+          index++
+          when (val escape = text[index]) {
+            '"' -> out.append('"')
+            '\\' -> out.append('\\')
+            '/' -> out.append('/')
+            'b' -> out.append('\b')
+            'f' -> out.append('\u000C')
+            'n' -> out.append('\n')
+            'r' -> out.append('\r')
+            't' -> out.append('\t')
+            'u' -> {
+              out.append(text.substring(index + 1, index + 5).toInt(16).toChar())
+              index += 4
+            }
+            else -> throw IllegalStateException("bad escape $escape")
+          }
+          index++
+        }
+        else -> {
+          out.append(char)
+          index++
+        }
+      }
+    }
+  }
+
+  /**
+   * A number with no `.`, `e` or `E` parses as Long. That distinction is not
+   * cosmetic: session numbers and epoch timestamps are integers, and reloading
+   * them as doubles would rewrite the persisted blob with decimal points the
+   * TypeScript reader has never seen.
+   */
+  private fun parseNumber(): Any {
+    val start = index
+    if (text[index] == '-' || text[index] == '+') index++
+    var floating = false
+    while (index < text.length) {
+      val char = text[index]
+      if (char in '0'..'9') {
+        index++
+      } else if (char == '.' || char == 'e' || char == 'E' || char == '+' || char == '-') {
+        floating = floating || char == '.' || char == 'e' || char == 'E'
+        index++
+      } else {
+        break
+      }
+    }
+    val token = text.substring(start, index)
+    if (token.isEmpty()) throw IllegalStateException("expected number")
+    return if (floating) token.toDouble() else token.toLong()
+  }
+}

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

@@ -0,0 +1,47 @@
+package io.advenue.core
+
+/**
+ * Client-side enforcement of the ingest schema's input budgets.
+ *
+ * Without this the SDK enqueues an event the server is guaranteed to reject,
+ * and the rejection is not per-event: `apps/ingestion/src/app.ts` parses the
+ * batch as a whole and answers 400 on any single invalid event.
+ *
+ * No valid events are lost — `flush()` answers a non-retryable 4xx by isolating
+ * the batch one event at a time. What it costs is that isolation pass: one
+ * failed batch POST followed by up to `batchSize` individual POSTs, on a mobile
+ * radio, to deliver events that would have gone in a single request. The
+ * offending event is discarded either way.
+ *
+ * Rejecting here loses exactly the same one event, spends no requests, and
+ * tells the app through `onError` instead of failing silently.
+ *
+ * The values mirror `packages/shared/src/events.ts`, which is the authority.
+ */
+
+/** `clientEventSchema.name` — z.string().min(1).max(128). */
+internal const val MAX_NAME_LENGTH: Int = 128
+
+/** `propertiesSchema` — at most this many keys. */
+internal const val MAX_PROPERTIES_KEYS: Int = 50
+
+/** `propertiesSchema` — the serialised length must not exceed this. */
+internal const val MAX_PROPERTIES_BYTES: Int = 8192
+
+/** Stable reason string, or null when the input is acceptable. */
+internal fun checkTrackInput(name: String, properties: Map<String, Any?>? = null): String? {
+  if (name.isEmpty()) return "name_empty"
+  if (name.length > MAX_NAME_LENGTH) return "name_too_long"
+  if (properties == null) return null
+  if (properties.size > MAX_PROPERTIES_KEYS) return "properties_too_many_keys"
+  val serialised =
+    try {
+      writeCanonicalJson(properties)
+    } catch (_: IllegalArgumentException) {
+      // A value the writer refuses would otherwise throw inside the transport,
+      // after it had already displaced a queue slot.
+      return "properties_unserialisable"
+    }
+  if (serialised.length > MAX_PROPERTIES_BYTES) return "properties_too_large"
+  return null
+}

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

@@ -0,0 +1,80 @@
+package io.advenue.core
+
+/**
+ * A Meta install referrer, parsed.
+ *
+ * [encryptedData] and [nonce] are the claim the server decrypts with the app's
+ * Meta decryption key; the key never reaches the device, so the SDK carries the
+ * ciphertext and nothing more.
+ */
+internal data class MetaReferrer(
+  val source: String?,
+  val campaign: String?,
+  val isClickThrough: Boolean,
+  /** Meta's own click/view time, in seconds. */
+  val timestamp: Long,
+  val encryptedData: String?,
+  val nonce: String?,
+  /** The provider's string, verbatim, for diagnostics. */
+  val raw: String,
+)
+
+/**
+ * Parses what the Meta install-referrer provider returned.
+ *
+ * Meta ships two shapes through the same column and the difference is not
+ * documented as a version: a JSON object when the referrer carries an encrypted
+ * claim, and a plain utm query string otherwise. Reading only the first would
+ * drop every organic-looking Meta install; reading only the second would drop
+ * every claim the server can actually decrypt.
+ *
+ * The JSON branch is tried first and, when the blob parses as an object, it
+ * OWNS the result — falling through to the query-string parser on a JSON object
+ * that merely lacks a claim would read the whole blob as one malformed key and
+ * report a campaign that does not exist.
+ *
+ * `network` is deliberately not derived here. The server assigns it from the
+ * decrypted claim (`meta_referrer` for a click, `meta_referrer_view` for a
+ * view), and a second answer set on the device would compete with the one that
+ * actually knows.
+ */
+internal fun parseMetaInstallReferrer(
+  raw: String,
+  isClickThrough: Boolean,
+  actualTimestamp: Long,
+): MetaReferrer? {
+  if (raw.isEmpty()) return null
+
+  val json = parseJson(raw) as? Map<*, *>
+  if (json != null) {
+    val claim = ((json["utm_content"] as? Map<*, *>)?.get("source")) as? Map<*, *>
+    // All or nothing. The server needs BOTH halves to decrypt, so a lone nonce
+    // is not half a claim — it is noise on the event that nothing will read.
+    val data = claim?.get("data") as? String
+    val nonce = claim?.get("nonce") as? String
+    val paired = if (!data.isNullOrEmpty() && !nonce.isNullOrEmpty()) data to nonce else null
+    return MetaReferrer(
+      source = json["utm_source"] as? String,
+      campaign = json["utm_campaign"] as? String,
+      isClickThrough = isClickThrough,
+      timestamp = actualTimestamp,
+      // Strings only. A number where `data` belongs is a shape the server
+      // cannot decrypt, and sending it credits the install to nobody — worse
+      // than reporting no claim at all.
+      encryptedData = paired?.first,
+      nonce = paired?.second,
+      raw = raw,
+    )
+  }
+
+  val parsed = parseInstallReferrer(raw)
+  return MetaReferrer(
+    source = parsed.source,
+    campaign = parsed.campaign,
+    isClickThrough = isClickThrough,
+    timestamp = actualTimestamp,
+    encryptedData = null,
+    nonce = null,
+    raw = raw,
+  )
+}

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