@advenue/react-native 1.0.1 → 1.1.0

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

@@ -24,23 +24,37 @@ public class HttpConversionFetcher(
   private val timeoutMs: Int = 15_000,
 ) : ConversionFetcher {
 
-  override fun fetch(): ConversionResult {
+  internal val requestMethod: String = "GET"
+
+  /**
+   * Sends `?platform=android`: this fetcher is Android-only by construction,
+   * and a project key spans listings, so the server needs the platform to pick
+   * the one this install was filed under (Y-LINKS-1). Without it the lookup
+   * refused the project key the dashboard mints, and the deferred deep link
+   * never arrived. No `store`: the SDK does not report one on events either, so
+   * both sides fall back to the project's default Android store.
+   */
+  internal fun requestUrl(): URL {
     val escaped = URLEncoder.encode(deviceId, "UTF-8")
-    val connection =
-      URL("$endpoint/sdk/conversion-data?deviceId=$escaped").openConnection()
-        as HttpURLConnection
+    return URL("$endpoint/sdk/conversion-data?deviceId=$escaped&platform=android")
+  }
+
+  internal fun requestHeaders(): Map<String, String> = mapOf("x-api-key" to apiKey)
+
+  override fun fetch(): ConversionResult {
+    val connection = requestUrl().openConnection() as HttpURLConnection
     try {
-      connection.requestMethod = "GET"
+      connection.requestMethod = requestMethod
       connection.connectTimeout = timeoutMs
       connection.readTimeout = timeoutMs
-      connection.setRequestProperty("x-api-key", apiKey)
+      for ((name, value) in requestHeaders()) connection.setRequestProperty(name, value)
 
       val status =
         try {
           connection.responseCode
-        } catch (_: IOException) {
+        } catch (error: IOException) {
           // No status to reason about; 408 marks it retryable, as sdk-core does.
-          throw IngestError(408)
+          throw IngestError(408, networkCause = error.javaClass.simpleName)
         }
       if (status < 200 || status >= 300) throw IngestError(status)
 
@@ -59,8 +73,8 @@ public class HttpConversionFetcher(
       )
     } catch (error: IngestError) {
       throw error
-    } catch (_: IOException) {
-      throw IngestError(408)
+    } catch (error: IOException) {
+      throw IngestError(408, networkCause = error.javaClass.simpleName)
     } finally {
       connection.disconnect()
     }

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

@@ -38,9 +38,16 @@ internal enum class ForegroundTransition {
  * `ProcessLifecycleOwner`'s constant. We cannot take the dependency, but we can
  * take its number.
  */
-internal class ForegroundTracker {
+internal class ForegroundTracker(seededInForeground: Boolean = false) {
   private var started = 0
-  private var inForeground = false
+
+  /**
+   * Seeded by initialize to match the session it did or did not open. Seeded
+   * as foregrounded, the launcher activity's first start is not a second
+   * foreground, and the stop of an activity that started before the bridge
+   * was registered still reaches the background.
+   */
+  private var inForeground = seededInForeground
   private var backgroundPending = false
 
   public fun onSignal(signal: LifecycleSignal): ForegroundTransition =

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

@@ -5,6 +5,7 @@ import io.advenue.core.ClientEvent
 import io.advenue.core.EventTransport
 import io.advenue.core.IngestError
 import io.advenue.core.JvmHmacSigner
+import io.advenue.core.iso8601
 import io.advenue.core.Signer
 import io.advenue.core.signRequest
 import io.advenue.core.parseJson
@@ -48,8 +49,17 @@ internal class HttpUrlTransport(
    * wire shape without a network round trip, which is the part that has to be
    * right.
    */
-  internal fun buildBody(events: List<ClientEvent>): String =
-    writeCanonicalJson(mapOf("apiKey" to apiKey, "events" to events.map { it.toMap() }))
+  internal fun buildBody(events: List<ClientEvent>, nowMs: Long = clock.nowMs()): String =
+    writeCanonicalJson(
+      mapOf(
+        "apiKey" to apiKey,
+        "events" to events.map { it.toMap() },
+        // The device clock at THIS attempt (spec 2026-10-01-data-fidelity D3):
+        // the server compares it with its receive time to measure the clock
+        // offset, so it is stamped per send and never persisted with the queue.
+        "sentAt" to iso8601(nowMs),
+      ),
+    )
 
   /** The headers for [body]; empty of signature headers when no secret is set. */
   internal fun buildHeaders(body: String, timestamp: String): Map<String, String> {
@@ -61,8 +71,11 @@ internal class HttpUrlTransport(
   }
 
   override fun send(events: List<ClientEvent>) {
-    val body = buildBody(events)
-    val headers = buildHeaders(body, clock.nowMs().toString())
+    // One reading for both `sentAt` and the signed timestamp: they describe the
+    // same instant, and two reads could straddle a clock change.
+    val nowMs = clock.nowMs()
+    val body = buildBody(events, nowMs)
+    val headers = buildHeaders(body, nowMs.toString())
 
     val connection = URL("$endpoint/v1/events").openConnection() as HttpURLConnection
     try {
@@ -77,9 +90,9 @@ internal class HttpUrlTransport(
       val status =
         try {
           connection.responseCode
-        } catch (_: IOException) {
+        } catch (error: IOException) {
           // No response at all is a transient failure, not a poison payload.
-          throw IngestError(408)
+          throw IngestError(408, networkCause = error.javaClass.simpleName)
         }
       if (status < 200 || status >= 300) throw IngestError(status)
 
@@ -92,8 +105,8 @@ internal class HttpUrlTransport(
       }
     } catch (error: IngestError) {
       throw error
-    } catch (_: IOException) {
-      throw IngestError(408)
+    } catch (error: IOException) {
+      throw IngestError(408, networkCause = error.javaClass.simpleName)
     } finally {
       connection.disconnect()
     }

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

@@ -28,6 +28,13 @@ import java.util.concurrent.TimeUnit
  */
 internal const val REFERRER_DEADLINE_MS: Long = 5_000
 
+/**
+ * How long past [REFERRER_DEADLINE_MS] flushes stay held for a pending install:
+ * the enrichment thread still has to submit the install through the pipe after
+ * its deadline.
+ */
+internal const val INSTALL_HOLD_MARGIN_MS: Long = 2_000
+
 /** A shorter budget for the enrichment that is not attribution-critical. */
 internal const val ENRICHMENT_DEADLINE_MS: Long = 3_000
 

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

@@ -1,6 +1,7 @@
 package io.advenue.platform
 
 import android.app.Activity
+import android.app.ActivityManager
 import android.app.Application
 import android.os.Bundle
 import android.os.Handler
@@ -19,8 +20,9 @@ internal class LifecycleBridge(
   private val application: Application,
   private val onForeground: () -> Unit,
   private val onBackground: () -> Unit,
+  seededInForeground: Boolean,
 ) : Application.ActivityLifecycleCallbacks {
-  private val tracker = ForegroundTracker()
+  private val tracker = ForegroundTracker(seededInForeground)
   private val handler = Handler(Looper.getMainLooper())
   private val debounce = Runnable { apply(tracker.onSignal(LifecycleSignal.DebounceElapsed)) }
 
@@ -70,3 +72,23 @@ internal class LifecycleBridge(
 
   override fun onActivityDestroyed(activity: Activity): Unit = Unit
 }
+
+/**
+ * Whether this process is running for a user-visible launch, read at
+ * initialize. `Application.onCreate` runs for a tapped icon and equally for a
+ * push, a WorkManager job or a broadcast that wakes the process with no
+ * activity; only the first is a session. During a user launch the system has
+ * already made the process top, so its importance is `IMPORTANCE_FOREGROUND`;
+ * a background wake reports a service or cached importance. The same check
+ * crash reporters use to tell a cold start from a background start. True
+ * wherever it cannot be read, which keeps the pre-existing behaviour: the
+ * launch is a foreground.
+ */
+internal fun readLaunchedInForeground(): Boolean =
+  try {
+    val info = ActivityManager.RunningAppProcessInfo()
+    ActivityManager.getMyMemoryState(info)
+    info.importance == ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND
+  } catch (_: Throwable) {
+    true
+  }

package/dist/index.cjs

@@ -65,7 +65,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@advenue/react-native",
-  version: "1.0.1",
+  version: "1.1.0",
   description: "Advenue MMP React Native SDK \u2014 attribution, install tracking, and deep links (bundled iOS/Android Expo native modules)",
   type: "module",
   license: "MIT",
@@ -225,6 +225,7 @@ var started = false;
 var deepLinkSub = null;
 var errorSub = null;
 var onErrorHook;
+var debugLogging = false;
 var consentCache = false;
 function bridge() {
   return { ios: getIosNative(), android: getAndroidNative() };
@@ -249,6 +250,7 @@ function report(context, cause) {
     onErrorHook?.(context, cause);
   } catch {
   }
+  if (debugLogging) console.warn(`[Advenue] ${context}`, cause);
 }
 function requireStarted() {
   if (started) return true;
@@ -262,6 +264,7 @@ var Advenue = {
    */
   async initialize(config) {
     onErrorHook = config.onError;
+    debugLogging = config.debug === true;
     for (const option of IGNORED_OPTIONS) {
       if (config[option] !== void 0) {
         report(
@@ -280,7 +283,11 @@ var Advenue = {
       signingSecret: config.signingSecret,
       fbAppId: config.fbAppId,
       autoTrackInstall: config.autoTrackInstall !== false,
-      sdkVersion: package_default.version
+      // Names the wrapper, like Flutter's `advenue_sdk/…`: a bare version reads
+      // like the native SDK's own stamp.
+      sdkVersion: `react-native/${package_default.version}`,
+      debug: config.debug === true,
+      allowInsecureHttp: config.allowInsecureHttp === true
     });
     started = true;
     const { ios: iosForErrors, android: androidForErrors } = bridge();

package/dist/index.d.cts

@@ -54,14 +54,12 @@ interface TrackOptions {
 interface AdvenueConfig {
     apiKey: string;
     endpoint?: string;
-    platform?: 'ios' | 'android' | 'web' | string;
     /**
      * @deprecated Ignored: the native SDK resolves the app version from the
      * package/bundle. Passing it reports `config.ignored:appVersion` via
      * `onError`. Removed in the next major.
      */
     appVersion?: string;
-    osVersion?: string;
     /** Gates every event on `setTrackingConsent(true)`. */
     requireConsent?: boolean;
     /** Events per request. */
@@ -74,9 +72,21 @@ interface AdvenueConfig {
      * extracted from it.
      */
     signingSecret?: string;
-    disableAutoSessions?: boolean;
+    /**
+     * **Test only.** Allows an `http://` endpoint — a local self-hosted ingest,
+     * or a test server — which the native SDKs otherwise refuse at initialize.
+     * Never set it in a production build: everything, the API key included,
+     * then travels unencrypted.
+     */
+    allowInsecureHttp?: boolean;
     /** Called when the SDK swallows a best-effort failure. Never receives PII. */
     onError?: (context: string, cause: unknown) => void;
+    /**
+     * Development aid: the native SDKs log their start, every swallowed failure
+     * and each sent batch to Xcode's console / logcat, and every failure is also
+     * written to the JS console as `[Advenue] <context>`. Never logs an
+     * identifier or a payload. Leave off in production; use `onError`.
+     */
     debug?: boolean;
 }
 

package/dist/index.d.ts

@@ -54,14 +54,12 @@ interface TrackOptions {
 interface AdvenueConfig {
     apiKey: string;
     endpoint?: string;
-    platform?: 'ios' | 'android' | 'web' | string;
     /**
      * @deprecated Ignored: the native SDK resolves the app version from the
      * package/bundle. Passing it reports `config.ignored:appVersion` via
      * `onError`. Removed in the next major.
      */
     appVersion?: string;
-    osVersion?: string;
     /** Gates every event on `setTrackingConsent(true)`. */
     requireConsent?: boolean;
     /** Events per request. */
@@ -74,9 +72,21 @@ interface AdvenueConfig {
      * extracted from it.
      */
     signingSecret?: string;
-    disableAutoSessions?: boolean;
+    /**
+     * **Test only.** Allows an `http://` endpoint — a local self-hosted ingest,
+     * or a test server — which the native SDKs otherwise refuse at initialize.
+     * Never set it in a production build: everything, the API key included,
+     * then travels unencrypted.
+     */
+    allowInsecureHttp?: boolean;
     /** Called when the SDK swallows a best-effort failure. Never receives PII. */
     onError?: (context: string, cause: unknown) => void;
+    /**
+     * Development aid: the native SDKs log their start, every swallowed failure
+     * and each sent batch to Xcode's console / logcat, and every failure is also
+     * written to the JS console as `[Advenue] <context>`. Never logs an
+     * identifier or a payload. Leave off in production; use `onError`.
+     */
     debug?: boolean;
 }
 

package/dist/index.js

@@ -54,7 +54,7 @@ var require_native_require = __commonJS({
 // package.json
 var package_default = {
   name: "@advenue/react-native",
-  version: "1.0.1",
+  version: "1.1.0",
   description: "Advenue MMP React Native SDK \u2014 attribution, install tracking, and deep links (bundled iOS/Android Expo native modules)",
   type: "module",
   license: "MIT",
@@ -214,6 +214,7 @@ var started = false;
 var deepLinkSub = null;
 var errorSub = null;
 var onErrorHook;
+var debugLogging = false;
 var consentCache = false;
 function bridge() {
   return { ios: getIosNative(), android: getAndroidNative() };
@@ -238,6 +239,7 @@ function report(context, cause) {
     onErrorHook?.(context, cause);
   } catch {
   }
+  if (debugLogging) console.warn(`[Advenue] ${context}`, cause);
 }
 function requireStarted() {
   if (started) return true;
@@ -251,6 +253,7 @@ var Advenue = {
    */
   async initialize(config) {
     onErrorHook = config.onError;
+    debugLogging = config.debug === true;
     for (const option of IGNORED_OPTIONS) {
       if (config[option] !== void 0) {
         report(
@@ -269,7 +272,11 @@ var Advenue = {
       signingSecret: config.signingSecret,
       fbAppId: config.fbAppId,
       autoTrackInstall: config.autoTrackInstall !== false,
-      sdkVersion: package_default.version
+      // Names the wrapper, like Flutter's `advenue_sdk/…`: a bare version reads
+      // like the native SDK's own stamp.
+      sdkVersion: `react-native/${package_default.version}`,
+      debug: config.debug === true,
+      allowInsecureHttp: config.allowInsecureHttp === true
     });
     started = true;
     const { ios: iosForErrors, android: androidForErrors } = bridge();

package/ios/AdvenueIosModule.swift

@@ -44,11 +44,14 @@ public class AdvenueIosModule: Module {
         },
         // The wrapper's version, not this SDK's: a React Native release pins
         // the native snapshot inside it, so its version identifies both.
-        sdkVersion: options["sdkVersion"] as? String)
+        sdkVersion: options["sdkVersion"] as? String,
+        // Test only; decided at init, where the https precondition runs.
+        allowInsecureHttp: (options["allowInsecureHttp"] as? Bool) ?? false)
       if let flushInterval = options["flushIntervalMs"] as? Int {
         config.flushIntervalMs = flushInterval
       }
       if let batchSize = options["batchSize"] as? Int { config.batchSize = batchSize }
+      config.debug = (options["debug"] as? Bool) ?? false
       Advenue.initialize(config)
       // Firebase App Instance ID, when the host app already ships Firebase.
       // `AdvenueFirebase` guards its import with `#if canImport`, which is

package/ios/vendor/Advenue/Advenue.swift

@@ -129,14 +129,11 @@ public enum Advenue {
   /// is empty or a backoff window is open.
   public static func flush() { state.submit(.flush) }
 
-  public static func notifyForeground() { state.submit(.foreground) }
+  public static func notifyForeground() { state.notifyForeground() }
 
   /// Backgrounding both closes the session and flushes: a batch stranded at the
   /// moment the app leaves the foreground may not be sent for hours.
-  public static func notifyBackground() {
-    state.submit(.background)
-    state.submit(.flush)
-  }
+  public static func notifyBackground() { state.notifyBackground() }
 
   /// Presents the ATT prompt. The app decides when; the SDK never prompts on
   /// its own.
@@ -167,10 +164,14 @@ final class AcceptedAppId: @unchecked Sendable {
     return value
   }
 
-  func set(_ appId: String) {
+  /// True the first time this app id is seen.
+  @discardableResult
+  func set(_ appId: String) -> Bool {
     lock.lock()
+    defer { lock.unlock() }
+    let changed = value != appId
     value = appId
-    lock.unlock()
+    return changed
   }
 }
 
@@ -209,17 +210,21 @@ final class FacadeState: @unchecked Sendable {
     transport: (any EventTransport)? = nil,
     sources: EnrichmentSources? = nil,
     skan skanReporter: (any SkanReporter)? = nil,
-    appVersion readVersion: () -> String? = readAppVersion
+    appVersion readVersion: () -> String? = readAppVersion,
+    launchedInBackground: () -> Bool = readLaunchedInBackground,
+    logSink: (any AdvenueLogSink)? = nil
   ) {
     // 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.
+    let (config, log) = withDebugLogging(config, sink: 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 != nil {
-      config.onError(
-        "config.ignored:appVersion",
-        IngestError(status: 0))
+      config.onError("config.ignored:appVersion", AdvenueSetupError.appVersionIgnored)
     }
 
     // B4: kuyruk blob'u Caches dosyalarına (yedek dışı); UserDefaults'ta
@@ -230,7 +235,7 @@ final class FacadeState: @unchecked Sendable {
       store = CompositeStore(files: files)
     } else {
       store = UserDefaultsStore()
-      config.onError("store.cache_unavailable", IngestError(status: 0))
+      config.onError("store.cache_unavailable", AdvenueSetupError.cacheUnavailable)
     }
     let secure = KeychainStore()
     let uuid = SystemUUIDs()
@@ -240,7 +245,7 @@ final class FacadeState: @unchecked Sendable {
       // Deferred: the Keychain could not be read. Nothing is minted and
       // nothing starts, so no event carries an invented identifier. The next
       // launch after first unlock resolves it.
-      config.onError("identity.deferred", IngestError(status: 0))
+      config.onError("identity.deferred", AdvenueSetupError.identityDeferred)
       return
     }
 
@@ -251,14 +256,19 @@ final class FacadeState: @unchecked Sendable {
       osVersion = nil
     #endif
 
-    let eventTransport =
+    let baseTransport =
       transport
       ?? HttpTransport(
         endpoint: config.endpoint, apiKey: config.apiKey,
         signingSecret: config.signingSecret,
         // Diagnostics only: it runs after the batch is already accepted, so
         // nothing it does can turn a successful ingest into a failure.
-        onAccepted: { [acceptedAppId] appId in acceptedAppId.set(appId) })
+        onAccepted: { [acceptedAppId] appId in
+          // A key pasted from the wrong app is otherwise silent.
+          if acceptedAppId.set(appId) { log("[Advenue] ingesting into app \(appId)") }
+        })
+    let eventTransport: any EventTransport =
+      config.debug ? LoggingTransport(inner: baseTransport, log: log) : baseTransport
 
     let engine = AdvenueEngine(
       config: EngineConfig(
@@ -330,13 +340,32 @@ final class FacadeState: @unchecked Sendable {
     pendingDeepLinks = []
     lock.unlock()
 
+    // 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 enrichment deadline by a margin and then lapses.
+    pipe.submit(.beginInstall(holdMs: INSTALL_WINDOW_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.
     for url in buffered { send(url) }
-    pipe.submit(.foreground)
+    // A launch into the background (fetch, silent push, location) is not a
+    // session: the first didBecomeActive opens it instead. iOS posts no
+    // didEnterBackground for an app that never left the background, so a
+    // tracker seeded as foregrounded would swallow the user's real open.
+    let inForeground = !launchedInBackground()
+    if inForeground { pipe.submit(.foreground) }
     // Seeded to match: the line above IS this launch's foreground, so the
     // activation notification that follows must not open a second session.
-    observeLifecycle(seededInForeground: true)
+    observeLifecycle(seededInForeground: inForeground)
+
+    log(
+      "[Advenue] initialized — endpoint \(config.endpoint), "
+        + "sdk \(config.sdkVersion ?? AdvenueVersion.current), "
+        // Not "background launch": a scene-based (SwiftUI) app is still
+        // reported in the background during didFinishLaunching even when the
+        // user opened it. Either way the session opens on activation.
+        + (inForeground ? "launched active" : "not active yet, the session opens on activation"))
 
     if config.flushIntervalMs > 0 {
       let timer = DispatchSource.makeTimerSource(queue: .global(qos: .utility))
@@ -593,6 +622,12 @@ final class FacadeState: @unchecked Sendable {
     #endif
   }
 
+  /// The public lifecycle calls go through the same tracker as UIKit's signals,
+  /// so one forwarded while already foregrounded (or already backgrounded) is a
+  /// no-op instead of a session split.
+  func notifyForeground() { handle(.didBecomeActive) }
+  func notifyBackground() { handle(.didEnterBackground) }
+
   /// Applies one lifecycle signal. Public routing lives here rather than in the
   /// observer closure so a test can drive it without UIKit.
   func handle(_ signal: LifecycleSignal) {

package/ios/vendor/Advenue/AdvenueConfig.swift

@@ -29,6 +29,12 @@ public struct AdvenueConfig: Sendable {
   /// Called when the SDK swallows a best-effort failure. Never receives PII.
   public var onError: @Sendable (String, any Error) -> Void
 
+  /// Development aid: logs the SDK's start, every failure `onError` sees and
+  /// each accepted batch to the unified log (subsystem `io.advenue.sdk`) —
+  /// Xcode's console and Console.app. Never logs an identifier or a payload.
+  /// Leave off in production; route failures through `onError` instead.
+  public var debug: Bool
+
   /// Overrides the version stamped on every event. Set by a WRAPPER SDK, never
   /// by an app.
   ///
@@ -61,7 +67,8 @@ public struct AdvenueConfig: Sendable {
     conversionValues: ConversionValueConfig? = nil,
     onError: @escaping @Sendable (String, any Error) -> Void = { _, _ in },
     sdkVersion: String? = nil,
-    allowInsecureHttp: Bool = false
+    allowInsecureHttp: Bool = false,
+    debug: Bool = false
   ) {
     precondition(
       allowInsecureHttp || Self.isSecureEndpoint(endpoint),
@@ -70,6 +77,7 @@ public struct AdvenueConfig: Sendable {
     self.endpoint = endpoint
     self.appVersion = appVersion
     self.requireConsent = requireConsent
+    self.debug = debug
     self.sessionWindowMs = sessionWindowMs
     self.batchSize = batchSize
     self.flushIntervalMs = flushIntervalMs
@@ -85,5 +93,5 @@ public struct AdvenueConfig: Sendable {
 /// release tag unless something checks. CI does, because the first question
 /// every field report raises is which build produced the event.
 public enum AdvenueVersion {
-  public static let current = "1.0.0"
+  public static let current = "1.1.0"
 }

package/ios/vendor/Advenue/AdvenueSetupError.swift

@@ -0,0 +1,24 @@
+/// A condition met while starting the SDK, reported through `onError` under
+/// the context in parentheses. Not a transport failure — these used to arrive
+/// as `IngestError(status: 0)`, which read as an HTTP error that never
+/// happened and named no cause.
+public enum AdvenueSetupError: Error, Equatable, Sendable, CustomStringConvertible {
+  /// `config.ignored:appVersion`
+  case appVersionIgnored
+  /// `store.cache_unavailable`
+  case cacheUnavailable
+  /// `identity.deferred`
+  case identityDeferred
+
+  public var description: String {
+    switch self {
+    case .appVersionIgnored:
+      return "appVersion is read from the bundle; the config value has no effect"
+    case .cacheUnavailable:
+      return "the Caches directory is unavailable; the event queue falls back to UserDefaults"
+    case .identityDeferred:
+      return "the Keychain is unavailable (not unlocked since boot, or the app is not "
+        + "code-signed); nothing starts until the next launch that can read it"
+    }
+  }
+}

package/ios/vendor/Advenue/DebugLog.swift

@@ -0,0 +1,46 @@
+import Foundation
+import os
+
+/// Where `AdvenueConfig.debug` writes. The unified logging system in an app;
+/// a recorder in tests.
+protocol AdvenueLogSink: Sendable {
+  func log(_ message: String)
+}
+
+/// `os.Logger`, public privacy: the lines carry failure contexts, counts and
+/// the app id the server resolved — never an identifier or a payload — and a
+/// debug aid that Console.app shows as `<private>` would not be one.
+struct UnifiedLogSink: AdvenueLogSink {
+  private let logger = Logger(subsystem: "io.advenue.sdk", category: "Advenue")
+  func log(_ message: String) {
+    logger.notice("\(message, privacy: .public)")
+  }
+}
+
+/// Logs each accepted batch; failures already reach the log through the
+/// wrapped `onError` (`flush.transport`, `flush.poison`).
+struct LoggingTransport: EventTransport {
+  let inner: any EventTransport
+  let log: @Sendable (String) -> Void
+
+  func send(_ events: [ClientEvent]) async throws {
+    try await inner.send(events)
+    log("[Advenue] sent \(events.count) 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.
+func withDebugLogging(
+  _ config: AdvenueConfig, sink: (any AdvenueLogSink)?
+) -> (AdvenueConfig, @Sendable (String) -> Void) {
+  guard config.debug else { return (config, { _ in }) }
+  let sink = sink ?? UnifiedLogSink()
+  var logged = config
+  let report = config.onError
+  logged.onError = { context, error in
+    sink.log("[Advenue] \(context): \(error)")
+    report(context, error)
+  }
+  return (logged, { sink.log($0) })
+}

package/ios/vendor/AdvenueCore/Backoff.swift

@@ -3,9 +3,23 @@ import Foundation
 /// A non-2xx ingest response. `isRetryable` separates a transient failure from
 /// a poison payload: retrying a 400 forever would block the queue head, and
 /// dropping a 429 would discard events over a throttle.
-public struct IngestError: Error, Equatable, Sendable {
+public struct IngestError: Error, Equatable, Sendable, CustomStringConvertible {
   public let status: Int
-  public init(status: Int) { self.status = status }
+  /// 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 let networkCause: String?
+
+  public init(status: Int, networkCause: String? = nil) {
+    self.status = status
+    self.networkCause = networkCause
+  }
+
+  public var description: String {
+    if let networkCause { return "IngestError: no response (network error: \(networkCause))" }
+    return "IngestError(status: \(status))"
+  }
 
   public var isRetryable: Bool {
     status == 408 || status == 429 || status >= 500