@advenue/react-native 1.0.0 → 1.1.0

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

@@ -44,7 +44,6 @@ class AdvenueAndroidModule : Module() {
         AdvenueConfig(
           apiKey = apiKey,
           endpoint = (options["endpoint"] as? String) ?: DEFAULT_ENDPOINT,
-          appVersion = options["appVersion"] as? String,
           requireConsent = (options["requireConsent"] as? Boolean) ?: false,
           batchSize = (options["batchSize"] as? Number)?.toInt() ?: 20,
           flushIntervalMs = (options["flushIntervalMs"] as? Number)?.toLong() ?: 15_000L,
@@ -58,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
@@ -30,6 +32,8 @@ import io.advenue.core.extractAemCampaignIds
 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
@@ -249,13 +253,27 @@ 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) {
+      config.onError(
+        "config.ignored:appVersion",
+        IllegalArgumentException("appVersion is resolved by the SDK and has no effect"),
+      )
+    }
     val scoped = InstallScopedStore(application)
     val prefs = PreferencesStore(application)
     val uuid = SystemUuids()
@@ -266,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,
@@ -280,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 =
@@ -292,12 +325,13 @@ internal class FacadeState {
             platform = "android",
             deviceId = identity.deviceId,
             installationId = identity.installationId,
-            appVersion = config.appVersion,
+            appVersion = readAppVersion(application),
             osVersion = Build.VERSION.RELEASE,
             sdkVersion = (config.sdkVersion ?: AdvenueVersion.CURRENT).take(32),
             requireConsent = config.requireConsent,
             sessionWindowMs = config.sessionWindowMs,
             batchSize = config.batchSize,
+            piiScrubEnabled = config.piiScrubEnabled,
           ),
         store = CompositeStore(prefs, scoped),
         clock = SystemClock(),
@@ -329,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,
@@ -343,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
@@ -368,6 +418,8 @@ internal class FacadeState {
               gaid = enrichment.gaid,
               androidId = null,
               appInstanceId = enrichment.appInstanceId,
+              // B2: bayrak artık düşürülmüyor — olaya işlenir.
+              limitAdTracking = enrichment.limitAdTracking,
             ),
           )
           // Device metadata rides the install, where Meta CAPI reads it.
@@ -458,7 +510,10 @@ internal class FacadeState {
   }
 
   private fun sendDeepLink(url: String) {
-    submit(Command.Track("deep_link", mapOf("url" to url), "custom"))
+    // B3: ham query gönderilmez — token/e-posta query'de taşınır. AEM
+    // ayrıştırması ve sourceUrlHash TAM url'den yapılır (aşağıda), yalnızca
+    // gönderilen `url` özelliği scheme+host+path'e indirgenir.
+    submit(Command.Track("deep_link", mapOf("url" to stripUrlQuery(url)), "custom"))
 
     // Meta AEM: a link from Meta carries al_applink_data with an opaque,
     // Meta-encrypted campaign_ids blob. Emitted at most once per URL — the
@@ -482,6 +537,7 @@ internal class FacadeState {
   private fun queryValue(url: String, name: String): String? =
     runCatching { android.net.Uri.parse(url).getQueryParameter(name) }.getOrNull()
 
+
   /** Test surface: how many links are waiting for `initialize`. */
   val bufferedDeepLinkCount: Int
     get() = synchronized(lock) { pendingDeepLinks.size }
@@ -547,3 +603,12 @@ internal class FacadeState {
     val app: Application?,
   )
 }
+
+/**
+ * B3: deep-link URL'sinden query+fragment atılır (token/e-posta taşınır).
+ * Saf dize işlemi — Android çalıştırıcısı gerekmez, JVM testinde de çalışır.
+ */
+internal fun stripUrlQuery(url: String): String {
+  val cut = url.indexOfAny(charArrayOf('?', '#'))
+  return if (cut >= 0) url.substring(0, cut) else url
+}

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

@@ -12,6 +12,7 @@ public data class AdvenueConfig
 constructor(
   val apiKey: String,
   val endpoint: String = DEFAULT_ENDPOINT,
+  /** Ignored: the SDK reads the app version from the package itself. Setting it reports `config.ignored:appVersion` through [onError]. Removed in the next major. */
   val appVersion: String? = null,
   val requireConsent: Boolean = false,
   val sessionWindowMs: Long = DEFAULT_SESSION_WINDOW_MS,
@@ -53,7 +54,30 @@ constructor(
    * iOS has no equivalent. A field on the Swift config would do nothing.
    */
   val fbAppId: String? = null,
+  /**
+   * B1: track properties PII scrub'u. Varsayılan-açık; yalnızca açıkça
+   * kapatın (dokümante risk — ham PII ingest'e gider). Swift ile aynı.
+   */
+  val piiScrubEnabled: Boolean = true,
+  /**
+   * B5: testler için `http://` izni. Üretimde kapalı tutun — açık `http://`
+   * 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,
+    // kurulumda yakalanır.
+    require(allowInsecureHttp || endpoint.startsWith("https://")) {
+      "Advenue endpoint must use https:// (set allowInsecureHttp only for tests)"
+    }
+  }
   /**
    * Java-friendly builder. Kotlin's named and default arguments are invisible
    * from Java, and both incumbents are Java-first — a Kotlin SDK that is painful
@@ -64,6 +88,7 @@ constructor(
 
     public fun endpoint(value: String): Builder = apply { config = config.copy(endpoint = value) }
 
+    /** Ignored — see [AdvenueConfig.appVersion]. */
     public fun appVersion(value: String?): Builder = apply {
       config = config.copy(appVersion = value)
     }
@@ -98,6 +123,16 @@ constructor(
       config = config.copy(fbAppId = value)
     }
 
+    public fun piiScrubEnabled(value: Boolean): Builder = apply {
+      config = config.copy(piiScrubEnabled = value)
+    }
+
+    public fun allowInsecureHttp(value: Boolean): Builder = apply {
+      config = config.copy(allowInsecureHttp = value)
+    }
+
+    public fun debug(value: Boolean): Builder = apply { config = config.copy(debug = value) }
+
     public fun build(): AdvenueConfig = config
   }
 }
@@ -110,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

@@ -19,12 +19,17 @@ internal sealed class Command {
     val gaid: String?,
     val androidId: String?,
     val appInstanceId: String?,
+    /** B2: reklam kimliği rıza bayrağı — toplanıp düşürülüyordu. */
+    val limitAdTracking: Boolean? = null,
   ) : Command()
 
   internal data class SetAppInstanceId(val id: String?) : 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()
@@ -121,26 +126,54 @@ internal class CommandPipe(
       is Command.SetConsent -> engine.setConsent(command.granted)
       is Command.SetUserId -> engine.setUserId(command.id)
       is Command.SetIdentity ->
-        engine.setIdentity(command.gaid, command.androidId, command.appInstanceId)
+        engine.setIdentity(
+          command.gaid,
+          command.androidId,
+          command.appInstanceId,
+          limitAdTracking = command.limitAdTracking,
+        )
       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

@@ -39,6 +39,9 @@ internal data class EngineConfig(
   val batchSize: Int = 20,
   val retryBaseMs: Double = 1_000.0,
   val retryCapMs: Double = 60_000.0,
+  /** B1: track properties PII scrub'u. Varsayılan-açık; yalnızca açık bayrakla
+   *  kapatılır (opt-out) ve bu dokümante risklidir. Swift EngineConfig ile aynı. */
+  val piiScrubEnabled: Boolean = true,
 )
 
 /**
@@ -72,9 +75,24 @@ internal class AdvenueEngine(
   private var gaid: String? = null
   private var androidId: String? = null
   private var appInstanceId: String? = null
+  /** B2: rıza bayrağı — her olaya işlenir, persist edilmez (kimlik gibi). */
+  private var limitAdTracking: Boolean? = null
   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
@@ -90,7 +108,12 @@ internal class AdvenueEngine(
       onError("track.rejected:$rejection", IngestError(400))
       return false
     }
-    queue.enqueue(newEvent(type = type, name = name, properties = properties))
+    // 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
   }
 
@@ -146,6 +169,12 @@ internal class AdvenueEngine(
     (parseJson(store.getString(CONSENT_DATA_KEY) ?: "") as? Map<*, *>)?.let(Consent::fromMap)
 
   public fun setUserId(id: String?) {
+    // B6: 128 üstü id tüm batch'i 400'e düşürür (ingest bütün-batch ayrıştırır).
+    // Reddet, persist etme, onError ile bildir (Limits.kt deseni).
+    if (id != null && id.length > MAX_USER_ID_LENGTH) {
+      onError("account.setUserId:id_too_long", IngestError(400))
+      return
+    }
     customerUserId = id
     if (id != null) store.setString(USER_ID_KEY, id) else store.remove(USER_ID_KEY)
   }
@@ -160,11 +189,13 @@ internal class AdvenueEngine(
     androidId: String?,
     appInstanceId: String?,
     idfa: String? = null,
+    limitAdTracking: Boolean? = null,
   ) {
     this.gaid = gaid
     this.androidId = androidId
     this.appInstanceId = appInstanceId
     this.idfa = idfa
+    this.limitAdTracking = limitAdTracking
   }
 
   /**
@@ -187,13 +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
-    queue.enqueue(newEvent(type = "install", name = "install", properties = properties))
+    // B1: install properties de scrub kapsamındadır.
+    val scrubbed = if (config.piiScrubEnabled) PiiScrub.scrub(properties) else properties
+    // 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.
    *
@@ -211,6 +284,7 @@ internal class AdvenueEngine(
    */
   public fun forgetMe() {
     forgotten = true
+    releaseInstallHold()
     queue.clear()
     sessions.reset()
     consent = false
@@ -231,6 +305,10 @@ internal class AdvenueEngine(
         DEVICE_ID_KEY,
         INSTALLATION_ID_KEY,
         INSTALL_SENT_KEY,
+        // queue.clear() above persists an empty blob synchronously; remove it
+        // so erasure leaves no queue file behind either. Safe to do last:
+        // `forgotten` stops every later enqueue, so nothing rewrites it.
+        QUEUE_KEY,
       )) {
       store.remove(key)
     }
@@ -269,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
@@ -387,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,
@@ -402,6 +493,7 @@ internal class AdvenueEngine(
       customerUserId = customerUserId,
       idfa = idfa,
       gaid = gaid,
+      limitAdTracking = limitAdTracking,
       androidId = androidId,
       appInstanceId = appInstanceId,
       consent = consentData?.toMap(),

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>) {

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

@@ -22,6 +22,9 @@ package io.advenue.core
 /** `clientEventSchema.name` — z.string().min(1).max(128). */
 internal const val MAX_NAME_LENGTH: Int = 128
 
+/** `customerUserId` — z.string().max(128). Üstü batch'i 400'e düşürür. */
+internal const val MAX_USER_ID_LENGTH: Int = 128
+
 /** `propertiesSchema` — at most this many keys. */
 internal const val MAX_PROPERTIES_KEYS: Int = 50