@advenue/react-native 1.0.1 → 1.1.1

package/android/build.gradle

@@ -8,14 +8,20 @@ plugins {
   id 'expo-module-gradle-plugin'
 }
 
+// Single source of truth, mirroring AdvenueIos.podspec (`s.version =
+// package['version']`): a hardcoded copy here shipped 0.6.3 while the
+// package was 1.1.0. Inert at runtime — an autolinked Expo module is never
+// published to Maven — but a wrong version misleads every build scan.
+def packageJson = new groovy.json.JsonSlurper().parseText(file('../package.json').text)
+
 group = 'expo.modules.advenue'
-version = '0.6.3'
+version = packageJson.version
 
 android {
   namespace "expo.modules.advenue"
   defaultConfig {
     versionCode 1
-    versionName "0.6.3"
+    versionName packageJson.version
   }
 }
 

package/android/src/main/java/expo/modules/advenue/AdvenueAndroidModule.kt

@@ -57,6 +57,10 @@ class AdvenueAndroidModule : Module() {
           // The JavaScript has sent this since before the inversion; nothing
           // read it, so Meta install-referrer attribution never ran.
           fbAppId = options["fbAppId"] as? String,
+          // Logs the start, failures and sent batches to logcat (tag Advenue).
+          debug = (options["debug"] as? Boolean) ?: false,
+          // Test only: an http:// endpoint is refused without it.
+          allowInsecureHttp = (options["allowInsecureHttp"] as? Boolean) ?: false,
         ),
       )
     }

package/android/src/main/kotlin/io/advenue/Advenue.kt

@@ -19,6 +19,8 @@ import io.advenue.core.SystemClock
 import io.advenue.core.SystemUuids
 import io.advenue.core.TimerScheduler
 import io.advenue.platform.HttpConversionFetcher
+import io.advenue.platform.INSTALL_HOLD_MARGIN_MS
+import io.advenue.platform.REFERRER_DEADLINE_MS
 import io.advenue.platform.HttpUrlTransport
 import io.advenue.platform.IdentityResolution
 import io.advenue.platform.EnrichmentSources
@@ -31,6 +33,7 @@ import io.advenue.core.tcfToConsent
 import io.advenue.platform.collectDeviceInfo
 import io.advenue.platform.readTcf
 import io.advenue.platform.readAppVersion
+import io.advenue.platform.readLaunchedInForeground
 import io.advenue.platform.collectEnrichment
 import io.advenue.platform.sha256Hex
 import io.advenue.platform.resolveIdentity
@@ -250,13 +253,19 @@ internal class FacadeState {
    */
   fun start(
     application: Application,
-    config: AdvenueConfig,
+    requested: AdvenueConfig,
     transport: EventTransport? = null,
     sources: EnrichmentSources? = null,
+    launchedInForeground: () -> Boolean = ::readLaunchedInForeground,
+    logSink: AdvenueLogSink? = null,
   ) {
     // Replace-and-shut-down, never add.
     stop()
 
+    // `debug`: every swallowed failure goes through onError, so logging there
+    // covers all of them — wrapped once, before anything below captures it.
+    val (config, log) = withDebugLogging(requested, logSink)
+
     // The SDK resolves the app version itself (readAppVersion); a config value
     // is ignored — and said so, rather than looking like it took effect.
     if (config.appVersion != null) {
@@ -275,12 +284,21 @@ internal class FacadeState {
       // and nothing starts, so no event carries an invented identifier. The
       // receiver below is the exit — without it the deferral would trade a
       // phantom id for permanent silence.
-      config.onError("identity.deferred", IngestError(0))
-      registerUnlockRetry(application, config, transport, sources)
+      // Reported as what it is: an IngestError(0) read as an HTTP failure
+      // that never happened, naming no cause.
+      config.onError(
+        "identity.deferred",
+        IllegalStateException(
+          "credential-encrypted storage is locked (not unlocked since boot); " +
+            "the SDK starts when the user unlocks the device",
+        ),
+      )
+      // The unwrapped config: the retry wraps it again on its own start.
+      registerUnlockRetry(application, requested, transport, sources)
       return
     }
 
-    val eventTransport =
+    val baseTransport =
       transport
         ?: HttpUrlTransport(
           endpoint = config.endpoint,
@@ -289,8 +307,14 @@ internal class FacadeState {
           clock = SystemClock(),
           // Diagnostics only: it runs after the batch is already accepted, so
           // nothing it does can turn a successful ingest into a failure.
-          onAccepted = { appId -> resolvedAppId = appId },
+          onAccepted = { appId ->
+            // A key pasted from the wrong app is otherwise silent.
+            if (resolvedAppId != appId) log("[Advenue] ingesting into app $appId")
+            resolvedAppId = appId
+          },
         )
+    val eventTransport =
+      if (config.debug) LoggingTransport(baseTransport, log) else baseTransport
 
     val scheduler = TimerScheduler()
     val engine =
@@ -339,10 +363,19 @@ internal class FacadeState {
       pendingDeepLinks = mutableListOf()
     }
 
+    // Before anything else is recorded: a launch that still owes its install
+    // stamps it now and holds every flush until the install is enqueued, so
+    // the server never sees this launch's session or events ahead of it. The
+    // hold outlives the referrer deadline by a margin and then lapses.
+    pipe.submit(Command.BeginInstall(REFERRER_DEADLINE_MS + INSTALL_HOLD_MARGIN_MS))
+
     // Replayed in arrival order, before the first session, so a deferred deep
     // link is attributed to the launch it belongs to.
     buffered.forEach { sendDeepLink(it) }
 
+    // A process woken with no activity (a push, a WorkManager job, a
+    // broadcast) is not a session: the first activity start opens it instead.
+    val inForeground = launchedInForeground()
     val bridge =
       LifecycleBridge(
         application,
@@ -353,12 +386,19 @@ internal class FacadeState {
           // for hours.
           pipe.submit(Command.Flush)
         },
+        // Seeded to match: the Foreground below IS this launch's session, so
+        // the launcher activity's start that follows must not open a second
+        // one — the engine would read the open session as a killed app and
+        // split it with a synthetic session_end.
+        seededInForeground = inForeground,
       )
     bridge.start()
-    // Application.onCreate runs before the first activity starts, so the
-    // foreground signal arrives from the bridge; a cold start where the SDK is
-    // initialised from an already-running activity still needs this.
-    pipe.submit(Command.Foreground)
+    if (inForeground) pipe.submit(Command.Foreground)
+    log(
+      "[Advenue] initialized — endpoint ${config.endpoint}, " +
+        "sdk ${config.sdkVersion ?: AdvenueVersion.CURRENT}, " +
+        if (inForeground) "foreground launch" else "background launch, no session yet",
+    )
 
     // Enrichment then install, off the caller's thread. initialize() returns
     // synchronously — an SDK that blocks Application.onCreate for five seconds

package/android/src/main/kotlin/io/advenue/AdvenueConfig.kt

@@ -64,6 +64,12 @@ constructor(
    * API anahtarı dahil tüm olayları şifresiz taşır.
    */
   val allowInsecureHttp: Boolean = false,
+  /**
+   * Development aid: logs the SDK's start, every failure [onError] sees and each
+   * accepted batch to logcat (tag `Advenue`). Never logs an identifier or a
+   * payload. Leave off in production; route failures through [onError] instead.
+   */
+  val debug: Boolean = false,
 ) {
   init {
     // B5: şemasız endpoint fail-fast — geçersiz şema transportta değil,
@@ -125,6 +131,8 @@ constructor(
       config = config.copy(allowInsecureHttp = value)
     }
 
+    public fun debug(value: Boolean): Builder = apply { config = config.copy(debug = value) }
+
     public fun build(): AdvenueConfig = config
   }
 }
@@ -137,5 +145,5 @@ constructor(
  * the event.
  */
 public object AdvenueVersion {
-  public const val CURRENT: String = "0.1.0"
+  public const val CURRENT: String = "1.1.0"
 }

package/android/src/main/kotlin/io/advenue/DebugLog.kt

@@ -0,0 +1,51 @@
+package io.advenue
+
+import android.util.Log
+import io.advenue.core.ClientEvent
+import io.advenue.core.EventTransport
+
+/** Where [AdvenueConfig.debug] writes: logcat in an app, a recorder in tests. */
+internal fun interface AdvenueLogSink {
+  fun log(message: String)
+}
+
+/** Logcat, tag `Advenue`. The lines carry failure contexts, counts and the app
+ *  id the server resolved — never an identifier or a payload. */
+internal object LogcatSink : AdvenueLogSink {
+  override fun log(message: String) {
+    Log.i("Advenue", message)
+  }
+}
+
+/** Logs each accepted batch; failures already reach the log through the
+ *  wrapped `onError` (`flush.transport`, `flush.poison`). */
+internal class LoggingTransport(
+  private val inner: EventTransport,
+  private val log: (String) -> Unit,
+) : EventTransport {
+  override fun send(events: List<ClientEvent>) {
+    inner.send(events)
+    log("[Advenue] sent ${events.size} event(s)")
+  }
+}
+
+/**
+ * With `debug` on: the config with `onError` also writing to the log, and the
+ * log itself. Off: the config unchanged and a log that discards.
+ */
+internal fun withDebugLogging(
+  config: AdvenueConfig,
+  sink: AdvenueLogSink?,
+): Pair<AdvenueConfig, (String) -> Unit> {
+  if (!config.debug) return config to {}
+  val out = sink ?: LogcatSink
+  val report = config.onError
+  val logged =
+    config.copy(
+      onError = { context, error ->
+        out.log("[Advenue] $context: $error")
+        report(context, error)
+      },
+    )
+  return logged to { message -> out.log(message) }
+}

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

@@ -5,7 +5,20 @@ package io.advenue.core
  * poison payload: retrying a 400 forever would block the queue head, and
  * dropping a 429 would discard events over a throttle.
  */
-internal class IngestError(public val status: Int) : Exception("advenue ingest failed: $status") {
+internal class IngestError(
+  public val status: Int,
+  /**
+   * Set when no response arrived at all — DNS, refused connection, timeout, no
+   * network. [status] is then 408 so the backoff retries it, but that 408 was
+   * never sent by a server, and logging it as one sends whoever debugs it
+   * looking at the wrong end (F-SDK-10).
+   */
+  public val networkCause: String? = null,
+) :
+  Exception(
+    if (networkCause != null) "advenue ingest failed: no response (network error: $networkCause)"
+    else "advenue ingest failed: $status",
+  ) {
   public val isRetryable: Boolean
     get() = status == 408 || status == 429 || status >= 500
 }

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

@@ -27,6 +27,9 @@ internal sealed class Command {
 
   public data class TrackInstall(val properties: Map<String, Any?>?) : Command()
 
+  /** A launch that still owes its install: hold flushes for at most [holdMs]. */
+  internal data class BeginInstall(val holdMs: Long) : Command()
+
   internal data class SetConsentData(val consent: Consent?) : Command()
 
   internal data class SetPushToken(val token: String?, val provider: String?) : Command()
@@ -131,23 +134,46 @@ internal class CommandPipe(
         )
       is Command.SetAppInstanceId -> engine.setAppInstanceId(command.id)
       is Command.TrackInstall -> engine.trackInstall(command.properties)
+      is Command.BeginInstall -> engine.beginInstall(command.holdMs)
       is Command.SetConsentData -> engine.setConsentData(command.consent)
       is Command.SetPushToken -> engine.setPushToken(command.token, command.provider)
       Command.ForgetMe -> engine.forgetMe()
       Command.Foreground -> engine.notifyForeground()
       Command.Background -> engine.notifyBackground()
-      Command.Flush -> engine.beginFlush()?.let { sends.put(Send(it, single = null)) }
+      Command.Flush -> {
+        val batch = engine.beginFlush()
+        if (batch != null) {
+          sends.put(Send(batch, single = null))
+        } else if (engine.isFlushing()) {
+          // Asked for while a batch is on the wire: run it when that send
+          // finishes rather than drop it — the events tracked meanwhile would
+          // otherwise wait a whole auto-flush interval.
+          flushRequested = true
+        }
+      }
       is Command.BatchOutcome ->
         engine.onBatchOutcome(command.error)?.let { sends.put(Send(listOf(it), single = it)) }
+          ?: flushIfRequested()
       is Command.SingleOutcome ->
         engine.onSingleOutcome(command.event, command.error)?.let {
           sends.put(Send(listOf(it), single = it))
-        }
+        } ?: flushIfRequested()
       is Command.RunScheduled -> command.work()
       Command.Shutdown -> Unit
     }
   }
 
+  /** Core-thread only, like everything [handle] touches. */
+  private var flushRequested = false
+
+  /** The flush a send in flight deferred, once that send is over. After a
+   *  transient failure the backoff makes this a no-op: the timer retries. */
+  private fun flushIfRequested() {
+    if (!flushRequested || engine.isFlushing()) return
+    flushRequested = false
+    engine.beginFlush()?.let { sends.put(Send(it, single = null)) }
+  }
+
   /**
    * Synchronous, non-blocking and **ordered** — the entire reason the ingress
    * is a queue.

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

@@ -80,6 +80,19 @@ internal class AdvenueEngine(
   private var consentData: Consent? = readConsentData()
   private var pushToken: String? = null
   private var pushProvider: String? = null
+  /**
+   * F-SDK-3: when this launch began an install that is not recorded yet. The
+   * install is stamped with it — the first open, not the moment the referrer
+   * read that preceded it finished.
+   */
+  private var installStartedAtMs: Long? = null
+
+  /**
+   * Flushes are held until the install is enqueued, so nothing reaches the
+   * server ahead of it. Bounded: past this instant the hold lapses, because a
+   * lost enrichment thread must never strand the queue.
+   */
+  private var installHoldUntilMs: Long? = null
   private var flushing = false
   private var consecutiveFailures = 0
   private var backoffUntilMs = 0L
@@ -98,6 +111,9 @@ internal class AdvenueEngine(
     // B1: PII scrub (Swift PIIScrub ile aynı sözleşme).
     val scrubbed = if (config.piiScrubEnabled) PiiScrub.scrub(properties) else properties
     queue.enqueue(newEvent(type = type, name = name, properties = scrubbed))
+    // An event is proof of life: a relaunch after an OS kill measures the gap
+    // from the last one (F-SDK-7).
+    sessions.heartbeat()
     return true
   }
 
@@ -202,15 +218,55 @@ internal class AdvenueEngine(
    * failure.
    */
   public fun trackInstall(properties: Map<String, Any?>? = null): Boolean {
+    val startedAtMs = installStartedAtMs
+    // Every outcome below ends the wait: recorded, refused or already sent,
+    // nothing is coming that the held events should still wait for.
+    releaseInstallHold()
     if (forgotten || (config.requireConsent && !consent)) return false
     if (store.getString(INSTALL_SENT_KEY) == "1") return false
     // B1: install properties de scrub kapsamındadır.
     val scrubbed = if (config.piiScrubEnabled) PiiScrub.scrub(properties) else properties
-    queue.enqueue(newEvent(type = "install", name = "install", properties = scrubbed))
+    // At the head: the session and custom events recorded while enrichment ran
+    // are already queued, and the install must reach the server before them.
+    queue.enqueueFirst(
+      newEvent(
+        type = "install",
+        name = "install",
+        properties = scrubbed,
+        timestampMs = startedAtMs ?: clock.nowMs(),
+      ),
+    )
     store.setString(INSTALL_SENT_KEY, "1")
     return true
   }
 
+  /**
+   * Marks the start of a launch that still owes its install. Called by the
+   * facade BEFORE the launch's foreground, while enrichment (Play referrer,
+   * advertising id, attestation) runs. Adjust and AppsFlyer both hold every
+   * later package behind the first one; this does the same, for at most
+   * [holdMs].
+   */
+  public fun beginInstall(holdMs: Long) {
+    if (forgotten || store.getString(INSTALL_SENT_KEY) == "1") return
+    val now = clock.nowMs()
+    installStartedAtMs = now
+    installHoldUntilMs = now + holdMs
+  }
+
+  /** Whether a pending install still holds flushes back. */
+  private fun heldForInstall(): Boolean {
+    val until = installHoldUntilMs ?: return false
+    if (clock.nowMs() < until) return true
+    installHoldUntilMs = null
+    return false
+  }
+
+  private fun releaseInstallHold() {
+    installStartedAtMs = null
+    installHoldUntilMs = null
+  }
+
   /**
    * Erasure, including the install-scoped identifiers.
    *
@@ -228,6 +284,7 @@ internal class AdvenueEngine(
    */
   public fun forgetMe() {
     forgotten = true
+    releaseInstallHold()
     queue.clear()
     sessions.reset()
     consent = false
@@ -290,9 +347,21 @@ internal class AdvenueEngine(
   /** Whether a transport is wired at all. */
   internal fun canFlush(): Boolean = transport != null
 
+  /** Whether a batch is on the wire (its outcome not yet consumed). */
+  internal fun isFlushing(): Boolean = flushing
+
   /** Decides what to send. Null means there is nothing to do. */
   internal fun beginFlush(): List<ClientEvent>? {
-    if (transport == null || flushing || queue.size == 0 || clock.nowMs() < backoffUntilMs) {
+    // The auto-flush timer is the foreground tick: it keeps the open
+    // sub-session's last activity fresh even when the app records nothing.
+    if (!forgotten) sessions.heartbeat()
+    if (
+      transport == null ||
+        flushing ||
+        queue.size == 0 ||
+        clock.nowMs() < backoffUntilMs ||
+        heldForInstall()
+    ) {
       return null
     }
     // Clamped to the wire's limit, not trusted. The server answers 400 for a
@@ -408,13 +477,14 @@ internal class AdvenueEngine(
     type: String,
     name: String,
     properties: Map<String, Any?>?,
+    timestampMs: Long = clock.nowMs(),
   ): ClientEvent =
     ClientEvent(
       id = uuid.next(),
       deviceId = config.deviceId,
       type = type,
       name = name,
-      timestamp = iso8601(clock.nowMs()),
+      timestamp = iso8601(timestampMs),
       platform = config.platform,
       installationId = config.installationId,
       appVersion = config.appVersion,

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

@@ -35,6 +35,18 @@ internal class EventQueue(
     schedulePersist()
   }
 
+  /**
+   * Puts an event at the HEAD of the queue — the install, which is the first
+   * package of an installation and must not be preceded by the session and
+   * custom events recorded while enrichment ran. Over the cap, the oldest
+   * events behind it are dropped, never the event just placed.
+   */
+  public fun enqueueFirst(event: ClientEvent) {
+    events.add(0, event)
+    while (events.size > maxSize) events.removeAt(1)
+    schedulePersist()
+  }
+
   public fun peek(max: Int): List<ClientEvent> = events.take(max)
 
   public fun ack(sent: List<ClientEvent>) {