@advenue/react-native 1.0.0 → 1.1.0

package/ios/vendor/AdvenueCore/Engine.swift

@@ -94,6 +94,14 @@ public actor AdvenueEngine {
     attestation: AttestationResult?, challenge: String?)?
   private var skan: SkanStateMachine?
   private var skanReporter: (any SkanReporter)?
+  /// 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
+  /// enrichment that preceded it finished.
+  private var installStartedAtMs: Int64?
+  /// 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 task must never strand the queue.
+  private var installHoldUntilMs: Int64?
   private var flushing = false
   private var consecutiveFailures = 0
   private var backoffUntilMs: Int64 = 0
@@ -147,6 +155,8 @@ public actor AdvenueEngine {
     event.sdkVersion = config.sdkVersion
     event.customerUserId = customerUserId
     event.idfa = idfa
+    // B2: rıza bayrağı olaya işlenir.
+    event.limitAdTracking = limitAdTracking
     event.vendorId = vendorId
     event.appInstanceId = appInstanceId
     event.consent = consentData
@@ -157,16 +167,26 @@ public actor AdvenueEngine {
     }
     event.properties = config.piiScrubEnabled ? PIIScrub.scrub(properties) : properties
     queue.enqueue(event)
+    // 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
   }
 
   /// Identity attached to every subsequent event. Not persisted: it is
   /// re-resolved each launch, because ATT status and the vendor id can both
   /// change between them.
-  public func setIdentity(idfa: String?, vendorId: String?, appInstanceId: String?) {
+  /// B2: rıza bayrağı — her olaya işlenir, persist edilmez (kimlik gibi).
+  private var limitAdTracking: Bool?
+
+  public func setIdentity(
+    idfa: String?, vendorId: String?, appInstanceId: String?,
+    limitAdTracking: Bool? = nil
+  ) {
     self.idfa = idfa
     self.vendorId = vendorId
     self.appInstanceId = appInstanceId
+    self.limitAdTracking = limitAdTracking
   }
 
   /// The Firebase App Instance ID alone. Separate from `setIdentity` because it
@@ -177,6 +197,30 @@ public actor AdvenueEngine {
     appInstanceId = id
   }
 
+  /// Marks the start of a launch that still owes its install. Called by the
+  /// platform layer BEFORE the launch's foreground, while enrichment (ATT,
+  /// AdServices, attestation) runs. Adjust and AppsFlyer both hold every later
+  /// package behind the first one; this does the same, for at most `holdMs`.
+  public func beginInstall(holdMs: Int) {
+    guard !forgotten, store.string(forKey: INSTALL_SENT_KEY) != "1" else { return }
+    let now = clock.nowMs()
+    installStartedAtMs = now
+    installHoldUntilMs = now + Int64(holdMs)
+  }
+
+  /// Whether a pending install still holds flushes back.
+  private func heldForInstall() -> Bool {
+    guard let until = installHoldUntilMs else { return false }
+    if clock.nowMs() < until { return true }
+    installHoldUntilMs = nil
+    return false
+  }
+
+  private func releaseInstallHold() {
+    installStartedAtMs = nil
+    installHoldUntilMs = nil
+  }
+
   /// The first-open event, at most once per installation. Returns whether it
   /// was recorded.
   ///
@@ -193,19 +237,29 @@ public actor AdvenueEngine {
     if forgotten { return false }
     if config.requireConsent && !consent {
       installDeferred = (adservicesToken, properties, attestation, attestationChallenge)
+      // Deferred possibly for good: the events consent does allow must not
+      // wait on it. Released on consent, the install is stamped then.
+      releaseInstallHold()
       return false
     }
-    if store.string(forKey: INSTALL_SENT_KEY) == "1" { return false }
+    if store.string(forKey: INSTALL_SENT_KEY) == "1" {
+      releaseInstallHold()
+      return false
+    }
+    let installedAtMs = installStartedAtMs ?? clock.nowMs()
+    releaseInstallHold()
 
     var event = ClientEvent(
       id: uuid.next(), deviceId: config.deviceId, type: "install", name: "install",
-      timestamp: EventEncoding.iso8601(ms: clock.nowMs()), platform: config.platform)
+      timestamp: EventEncoding.iso8601(ms: installedAtMs), platform: config.platform)
     event.installationId = config.installationId
     event.appVersion = config.appVersion
     event.osVersion = config.osVersion
     event.sdkVersion = config.sdkVersion
     event.customerUserId = customerUserId
     event.idfa = idfa
+    // B2: rıza bayrağı install olayına da işlenir.
+    event.limitAdTracking = limitAdTracking
     event.vendorId = vendorId
     event.appInstanceId = appInstanceId
     event.consent = consentData
@@ -230,7 +284,9 @@ public actor AdvenueEngine {
       merged = properties
     }
     event.properties = config.piiScrubEnabled ? PIIScrub.scrub(merged) : merged
-    queue.enqueue(event)
+    // 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(event)
 
     store.set("1", forKey: INSTALL_SENT_KEY)
     return true
@@ -347,6 +403,11 @@ public actor AdvenueEngine {
 
 
   public func setUserId(_ id: String?) {
+    // B6: 128 üstü id tüm batch'i 400'e düşürür. Reddet, persist etme.
+    if let id, id.count > 128 {
+      onError("account.setUserId:id_too_long", IngestError(status: 400))
+      return
+    }
     customerUserId = id
     if let id {
       store.set(id, forKey: USER_ID_KEY)
@@ -361,6 +422,7 @@ public actor AdvenueEngine {
   /// behind, which is an erasure that does not erase (spec §5).
   public func forgetMe() {
     forgotten = true
+    releaseInstallHold()
     queue.clear()
     sessions.reset()
     consent = false
@@ -368,7 +430,9 @@ public actor AdvenueEngine {
     pushToken = nil
     pushProvider = nil
     customerUserId = nil
-    for key in [CONSENT_KEY, CONSENT_DATA_KEY, SESSION_STATE_KEY, USER_ID_KEY] {
+    // QUEUE_KEY last: queue.clear() above persists an empty blob synchronously,
+    // and `forgotten` stops every later enqueue, so nothing rewrites it.
+    for key in [CONSENT_KEY, CONSENT_DATA_KEY, SESSION_STATE_KEY, USER_ID_KEY, QUEUE_KEY] {
       store.removeObject(forKey: key)
     }
   }
@@ -403,8 +467,13 @@ public actor AdvenueEngine {
   /// throws — a timer-driven call is unawaited, so a transient failure simply
   /// leaves the batch buffered for the next attempt.
   public func flush() async {
+    // 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() }
     guard let transport else { return }
-    if flushing || queue.size == 0 || clock.nowMs() < backoffUntilMs { return }
+    if flushing || queue.size == 0 || clock.nowMs() < backoffUntilMs || heldForInstall() {
+      return
+    }
     flushing = true
     defer { flushing = false }
 
@@ -477,7 +546,7 @@ public enum Command: Sendable {
   case foreground
   case background
   case flush
-  case setIdentity(idfa: String?, vendorId: String?, appInstanceId: String?)
+  case setIdentity(idfa: String?, vendorId: String?, appInstanceId: String?, limitAdTracking: Bool? = nil)
   case setAppInstanceId(String?)
   case setConsentData(Consent?)
   case setPushToken(token: String?, provider: String?)
@@ -488,6 +557,7 @@ public enum Command: Sendable {
     reporter: any SkanReporter, configVersion: Int)
   case trackInstall(
     adservicesToken: String?, attestation: AttestationResult?, attestationChallenge: String?)
+  case beginInstall(holdMs: Int)
 }
 
 /// The ordered ingress: a synchronous, non-blocking `submit` feeding one
@@ -543,10 +613,14 @@ public final class CommandPipe: @unchecked Sendable {
       await engine.notifyBackground()
     case .flush:
       await engine.flush()
-    case .setIdentity(let idfa, let vendorId, let appInstanceId):
-      await engine.setIdentity(idfa: idfa, vendorId: vendorId, appInstanceId: appInstanceId)
+    case .setIdentity(let idfa, let vendorId, let appInstanceId, let limitAdTracking):
+      await engine.setIdentity(
+        idfa: idfa, vendorId: vendorId, appInstanceId: appInstanceId,
+        limitAdTracking: limitAdTracking)
     case .setAppInstanceId(let id):
       await engine.setAppInstanceId(id)
+    case .beginInstall(let holdMs):
+      await engine.beginInstall(holdMs: holdMs)
     case .trackInstall(let token, let attestation, let challenge):
       await engine.trackInstall(
         adservicesToken: token, attestation: attestation, attestationChallenge: challenge)

package/ios/vendor/AdvenueCore/EventQueue.swift

@@ -49,6 +49,18 @@ public final 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 func enqueueFirst(_ event: ClientEvent) {
+    events.insert(event, at: 0)
+    if events.count > maxSize {
+      events.removeSubrange(1..<(1 + events.count - maxSize))
+    }
+    schedulePersist()
+  }
+
   public func peek(_ max: Int) -> [ClientEvent] {
     Array(events.prefix(max))
   }

package/ios/vendor/AdvenueCore/SessionTracker.swift

@@ -2,6 +2,9 @@ import Foundation
 
 public let SESSION_STATE_KEY = "advenue.session"
 public let DEFAULT_SESSION_WINDOW_MS: Int64 = 1_800_000  // 30 minutes
+/// The heartbeat persists at most this often: it runs on every recorded event,
+/// and a chatty app must not turn that into a storage write per event.
+public let SESSION_HEARTBEAT_MIN_INTERVAL_MS: Int64 = 1_000
 
 /// A session lifecycle event. Values are numbers, strings and bools only.
 public struct SessionEvent: Equatable, Sendable {
@@ -20,6 +23,10 @@ struct SessionState: Codable {
   var activeStart: Int64?
   var firstForegroundAt: Int64
   var timeSpentMs: Int64
+  /// The last moment the open sub-session was known to be alive (F-SDK-7).
+  /// Absent in state written before it existed, which reads as "alive at
+  /// activeStart".
+  var lastActiveAt: Int64?
 }
 
 /// Platform-agnostic session state machine. Pure: it persists state and
@@ -30,6 +37,11 @@ public final class SessionTracker {
   private let clock: Clock
   private let windowMs: Int64
   private let uuid: UUIDSource
+  /// True once THIS process opened the current sub-session (X-SDK-1). Never
+  /// persisted: a relaunched process starts false, so its tracks and flushes
+  /// before `handleForeground()` cannot keep the dead process's sub-session
+  /// alive and move its kill time to the relaunch.
+  private var ownsOpenSubSession = false
 
   public init(store: KeyValueStore, clock: Clock, windowMs: Int64, uuid: UUIDSource) {
     self.store = store
@@ -40,7 +52,10 @@ public final class SessionTracker {
 
   /// Drops the in-memory cache so a wiped store cannot be resurrected by a
   /// later lifecycle call (GDPR erasure).
-  public func reset() { cached = nil }
+  public func reset() {
+    cached = nil
+    ownsOpenSubSession = false
+  }
 
   private func load() -> SessionState? {
     if let cached { return cached }
@@ -58,14 +73,67 @@ public final class SessionTracker {
     store.set(String(decoding: data, as: UTF8.self), forKey: SESSION_STATE_KEY)
   }
 
-  /// Foreground transition, including cold start. Returns the events to emit:
-  /// none for a sub-session, one `session_start` for a new session, or a
-  /// synthetic `session_end` FOLLOWED BY the start when the previous session
-  /// was still open — the OS killed the app before it could background. The
-  /// order is load-bearing: a consumer must never see two sessions open.
+  /// Refreshes the open sub-session's last known activity. Called by the
+  /// engine on every recorded event and every flush — the auto-flush timer is
+  /// the foreground tick. It is what a relaunch after an OS kill measures the
+  /// gap from, the role Adjust's `lastActivity` plays.
+  ///
+  /// A no-op until this process has run `handleForeground()`: only the process
+  /// that opened the sub-session may extend it. Otherwise an event or flush in a
+  /// relaunched process (iOS `didFinishLaunching` runs before
+  /// `didBecomeActive`; push and background wakes) would stamp the killed
+  /// sub-session alive "now" and count the dead time as active (X-SDK-1).
+  public func heartbeat() {
+    guard ownsOpenSubSession else { return }
+    guard var state = load(), let activeStart = state.activeStart else { return }
+    let now = clock.nowMs()
+    if now - (state.lastActiveAt ?? activeStart) < SESSION_HEARTBEAT_MIN_INTERVAL_MS { return }
+    state.lastActiveAt = now
+    save(state)
+  }
+
+  /// Foreground transition, including cold start. Returns the events to emit,
+  /// in order:
+  ///
+  /// - a synthetic `session_end` first when a sub-session was still open — the
+  ///   OS killed the app before it could background. It is closed at its last
+  ///   heartbeat, not at the relaunch: the time the app was dead is not active
+  ///   time. A consumer must never see two sessions open, so it comes first.
+  /// - then, measured from the background (or that kill time): nothing for a
+  ///   sub-session inside the window, or a `session_start` for a new session.
+  ///
+  /// A kill is not a session boundary by itself (F-SDK-7). Adjust's rule — a
+  /// new session only after the session interval of inactivity — applies to a
+  /// relaunch exactly as it does to a return from the background.
   public func handleForeground() -> [SessionEvent] {
-    let state = load()
     let now = clock.nowMs()
+    guard var state = load(), let activeStart = state.activeStart else {
+      return resume(after: load(), now: now)
+    }
+
+    let killTime = min(now, max(activeStart, state.lastActiveAt ?? activeStart))
+    let activeMs = max(0, killTime - activeStart)
+    let timeSpentMs = state.timeSpentMs + activeMs
+    let end = SessionEvent(
+      name: "session_end",
+      properties: [
+        "sessionId": .string(state.sessionId),
+        "sessionNumber": .int(state.sessionNumber),
+        "subSession": .int(state.subSessionCount),
+        "activeMs": .int(Int(activeMs)),
+        "timeSpentMs": .int(Int(timeSpentMs)),
+        "sessionLengthMs": .int(Int(max(0, killTime - state.firstForegroundAt))),
+        "synthetic": .bool(true),
+      ])
+    state.lastBackgroundAt = killTime
+    state.activeStart = nil
+    state.lastActiveAt = nil
+    state.timeSpentMs = timeSpentMs
+    return [end] + resume(after: state, now: now)
+  }
+
+  /// The foreground decision once no sub-session is open.
+  private func resume(after state: SessionState?, now: Int64) -> [SessionEvent] {
     let gap: Int64? = state?.lastBackgroundAt.map { now - $0 }
 
     if state == nil || gap == nil || gap! >= windowMs {
@@ -75,40 +143,27 @@ public final class SessionTracker {
         SessionState(
           sessionId: sessionId, sessionNumber: sessionNumber, lastBackgroundAt: nil,
           subSessionCount: 1, activeStart: now, firstForegroundAt: now, timeSpentMs: 0))
+      ownsOpenSubSession = true
 
-      let start = SessionEvent(
-        name: "session_start",
-        properties: [
-          "sessionId": .string(sessionId),
-          "sessionNumber": .int(sessionNumber),
-          "subSession": .int(1),
-          "isFirstSession": .bool(sessionNumber == 1),
-          "timeSinceLastSessionMs": .int(Int(gap ?? 0)),
-        ])
-
-      if let prior = state, let activeStart = prior.activeStart {
-        let killTime = prior.lastBackgroundAt ?? now
-        let activeMs = max(0, killTime - activeStart)
-        let end = SessionEvent(
-          name: "session_end",
+      return [
+        SessionEvent(
+          name: "session_start",
           properties: [
-            "sessionId": .string(prior.sessionId),
-            "sessionNumber": .int(prior.sessionNumber),
-            "subSession": .int(prior.subSessionCount),
-            "activeMs": .int(Int(activeMs)),
-            "timeSpentMs": .int(Int(prior.timeSpentMs + activeMs)),
-            "sessionLengthMs": .int(Int(max(0, killTime - prior.firstForegroundAt))),
-            "synthetic": .bool(true),
+            "sessionId": .string(sessionId),
+            "sessionNumber": .int(sessionNumber),
+            "subSession": .int(1),
+            "isFirstSession": .bool(sessionNumber == 1),
+            "timeSinceLastSessionMs": .int(Int(gap ?? 0)),
           ])
-        return [end, start]
-      }
-      return [start]
+      ]
     }
 
     var updated = state!
     updated.subSessionCount += 1
     updated.activeStart = now
+    updated.lastActiveAt = nil
     save(updated)
+    ownsOpenSubSession = true
     return []
   }
 
@@ -123,8 +178,10 @@ public final class SessionTracker {
     let timeSpentMs = state.timeSpentMs + activeMs
     state.lastBackgroundAt = now
     state.activeStart = nil
+    state.lastActiveAt = nil
     state.timeSpentMs = timeSpentMs
     save(state)
+    ownsOpenSubSession = false
     return SessionEvent(
       name: "session_end",
       properties: [

package/ios/vendor/AdvenuePlatform/CacheFileStore.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// B4: dosya destekli anahtar-değer deposu. Caches dizini iCloud/yedek
+/// kapsamı dışındadır — kuyruk blob'u (reklam kimlikli olay gövdeleri)
+/// yedek imajına sızmaz. Linux taşınabilirliği için yalnızca Foundation.
+public struct CacheFileStore: KeyValueStore, @unchecked Sendable {
+  private let directory: URL
+  private let fileManager = FileManager.default
+
+  /// - Parameter directory: Kök dizin. Üretimde Caches/advenue kullanılır;
+  ///   testler geçici dizin verir.
+  public init(directory: URL) {
+    self.directory = directory
+  }
+
+  public static func caches() -> CacheFileStore? {
+    guard
+      let base = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first
+    else { return nil }
+    let directory = base.appendingPathComponent("advenue", isDirectory: true)
+    try? FileManager.default.createDirectory(
+      at: directory, withIntermediateDirectories: true)
+    return CacheFileStore(directory: directory)
+  }
+
+  private func file(forKey key: String) -> URL {
+    // Anahtar dosya adı olur — boş/kök kaçışı engellenir.
+    let safe = key.replacingOccurrences(of: "/", with: "_")
+    return directory.appendingPathComponent(safe, isDirectory: false)
+  }
+
+  public func string(forKey key: String) -> String? {
+    try? String(contentsOf: file(forKey: key), encoding: .utf8)
+  }
+
+  public func set(_ value: String, forKey key: String) {
+    try? fileManager.createDirectory(
+      at: directory, withIntermediateDirectories: true)
+    try? value.write(to: file(forKey: key), atomically: true, encoding: .utf8)
+  }
+
+  public func removeObject(forKey key: String) {
+    try? fileManager.removeItem(at: file(forKey: key))
+  }
+}
+
+/// B4: bileşik depo — kuyruk blob'u dosyalara (yedek dışı), geri kalan
+/// UserDefaults'a. Android `CompositeStore` ile aynı yönlendirme.
+/// Eski UserDefaults anahtarı ilk okumada migrate edilir (RN uyumluluğu).
+public struct CompositeStore: KeyValueStore, @unchecked Sendable {
+  private let defaults: UserDefaultsStore
+  private let files: CacheFileStore
+  private let fileKeys: Set<String>
+
+  public init(
+    defaults: UserDefaultsStore = UserDefaultsStore(),
+    files: CacheFileStore,
+    fileKeys: Set<String> = [QUEUE_KEY]
+  ) {
+    self.defaults = defaults
+    self.files = files
+    self.fileKeys = fileKeys
+  }
+
+  public func string(forKey key: String) -> String? {
+    guard fileKeys.contains(key) else { return defaults.string(forKey: key) }
+    if let hit = files.string(forKey: key) { return hit }
+    // Tek seferlik geriye dönük migrate: RN/önceki sürüm UserDefaults'ta bıraktı.
+    guard let legacy = defaults.string(forKey: key) else { return nil }
+    files.set(legacy, forKey: key)
+    defaults.removeObject(forKey: key)
+    return legacy
+  }
+
+  public func set(_ value: String, forKey key: String) {
+    if fileKeys.contains(key) {
+      files.set(value, forKey: key)
+    } else {
+      defaults.set(value, forKey: key)
+    }
+  }
+
+  public func removeObject(forKey key: String) {
+    if fileKeys.contains(key) {
+      files.removeObject(forKey: key)
+    } else {
+      defaults.removeObject(forKey: key)
+    }
+  }
+}

package/ios/vendor/AdvenuePlatform/ChallengeFetcher.swift

@@ -17,17 +17,29 @@ public struct HttpChallengeFetcher: ChallengeSource {
     self.session = session
   }
 
-  public func challenge(deviceId: String) async throws -> String {
+  /// The exact request this fetcher would send. Public so a test can assert
+  /// the wire shape without a network round trip.
+  ///
+  /// Sends `?platform=ios`: this fetcher is iOS-only by construction, and a
+  /// project-scoped key otherwise cannot resolve a listing on a normal
+  /// two-listing (iOS + Android) product — see `resolveProjectListing` in
+  /// apps/ingestion/src/app.ts, which 400s an ambiguous project key rather
+  /// than guess.
+  public func buildRequest(deviceId: String) -> URLRequest {
     let escaped =
       deviceId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? deviceId
     var request = URLRequest(
-      url: URL(string: "\(endpoint)/v1/attest/challenge?deviceId=\(escaped)")!)
+      url: URL(string: "\(endpoint)/v1/attest/challenge?deviceId=\(escaped)&platform=ios")!)
     request.httpMethod = "GET"
     request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
     // Matches the deadline the RN SDK uses. Attestation is enrichment: it never
     // holds the install.
     request.timeoutInterval = 5
+    return request
+  }
 
+  public func challenge(deviceId: String) async throws -> String {
+    let request = buildRequest(deviceId: deviceId)
     let (payload, response) = try await session.data(for: request)
     guard let http = response as? HTTPURLResponse,
       (200..<300).contains(http.statusCode)

package/ios/vendor/AdvenuePlatform/ConversionFetcher.swift

@@ -23,13 +23,24 @@ public struct HttpConversionFetcher: ConversionFetcher {
     self.session = session
   }
 
-  public func fetch() async throws -> ConversionResult {
+  /// Sends `?platform=ios`: this fetcher is iOS-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.
+  func buildRequest() -> URLRequest {
     let escaped =
       deviceId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? deviceId
-    var request = URLRequest(url: URL(string: "\(endpoint)/sdk/conversion-data?deviceId=\(escaped)")!)
+    var request = URLRequest(
+      url: URL(string: "\(endpoint)/sdk/conversion-data?deviceId=\(escaped)&platform=ios")!)
     request.httpMethod = "GET"
     request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
     request.timeoutInterval = 15
+    return request
+  }
+
+  public func fetch() async throws -> ConversionResult {
+    let request = buildRequest()
 
     let payload: Data
     let response: URLResponse
@@ -37,7 +48,7 @@ public struct HttpConversionFetcher: ConversionFetcher {
       (payload, response) = try await session.data(for: request)
     } catch {
       // No status to reason about; 408 marks it retryable, as sdk-core does.
-      throw IngestError(status: 408)
+      throw IngestError(status: 408, networkCause: describeNetworkFailure(error))
     }
     guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
     guard (200..<300).contains(http.statusCode) else {

package/ios/vendor/AdvenuePlatform/DeviceInfo.swift

@@ -4,6 +4,37 @@ import Foundation
   import UIKit
 #endif
 
+/// The app's own version (`CFBundleShortVersionString`) for every event's
+/// top-level `appVersion`. Resolved by the SDK, never taken from the app: the
+/// React Native 0.x layer filled it this way, and 1.0 relying on the config
+/// instead left every event unversioned (2026-09-19). Nil when the bundle has
+/// no version.
+public func readAppVersion() -> String? {
+  guard let short = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String,
+    !short.isEmpty
+  else { return nil }
+  return short
+}
+
+/// Whether this process was launched into the background — background fetch,
+/// a silent push, a location relaunch — rather than opened by the user. Read
+/// through the runtime, not `UIApplication.shared`: that symbol is unavailable
+/// in an app extension and merely referencing it there fails to link. False
+/// wherever it cannot be known (an extension, off the main thread, macOS),
+/// which keeps the pre-existing behaviour: the launch is a foreground.
+public func readLaunchedInBackground() -> Bool {
+  #if canImport(UIKit) && !os(watchOS)
+    guard Thread.isMainThread, !Bundle.main.bundlePath.hasSuffix(".appex") else { return false }
+    let selector = NSSelectorFromString("sharedApplication")
+    guard UIApplication.responds(to: selector),
+      let app = UIApplication.perform(selector)?.takeUnretainedValue() as? UIApplication
+    else { return false }
+    return app.applicationState == .background
+  #else
+    return false
+  #endif
+}
+
 /// Device metadata for Meta CAPI `extinfo`.
 ///
 /// Best-effort per field: a field is **omitted**, never defaulted, when its

package/ios/vendor/AdvenuePlatform/HttpTransport.swift

@@ -5,6 +5,10 @@ import Foundation
 struct EventBatch: Encodable {
   let apiKey: String
   let events: [ClientEvent]
+  /// The device clock at THIS send 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 on every attempt and never persisted with the queue.
+  let sentAt: String
 }
 
 public let DEFAULT_ENDPOINT = "https://ingest.advenue.io"
@@ -49,8 +53,12 @@ public struct HttpTransport: EventTransport, Sendable {
   /// the wire shape — endpoint, headers, body, signature — without a network
   /// round trip, which is the part that has to be right.
   public func buildRequest(_ events: [ClientEvent]) throws -> URLRequest {
+    // One reading for both `sentAt` and the signed timestamp: they describe
+    // the same instant, and two reads could straddle a clock change.
+    let nowMs = clock.nowMs()
     let body = try EventEncoding.canonicalEncoder()
-      .encode(EventBatch(apiKey: apiKey, events: events))
+      .encode(
+        EventBatch(apiKey: apiKey, events: events, sentAt: EventEncoding.iso8601(ms: nowMs)))
     var request = URLRequest(url: URL(string: "\(endpoint)/v1/events")!)
     request.httpMethod = "POST"
     request.setValue("application/json", forHTTPHeaderField: "content-type")
@@ -58,7 +66,7 @@ public struct HttpTransport: EventTransport, Sendable {
     request.timeoutInterval = 15
 
     if let secret = signingSecret {
-      let timestamp = String(clock.nowMs())
+      let timestamp = String(nowMs)
       request.setValue(timestamp, forHTTPHeaderField: "X-Advenue-Timestamp")
       request.setValue(
         signRequest(
@@ -77,8 +85,8 @@ public struct HttpTransport: EventTransport, Sendable {
       (payload, response) = try await session.data(for: request)
     } catch {
       // No status to reason about. 408 marks it retryable, which is what
-      // sdk-core does for the same case.
-      throw IngestError(status: 408)
+      // sdk-core does for the same case; the cause says it was the network.
+      throw IngestError(status: 408, networkCause: describeNetworkFailure(error))
     }
     guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
     guard (200..<300).contains(http.statusCode) else {
@@ -94,3 +102,19 @@ public struct HttpTransport: EventTransport, Sendable {
     }
   }
 }
+
+/// A short, identifier-free name for a failure that produced no response.
+func describeNetworkFailure(_ error: any Error) -> String {
+  guard let urlError = error as? URLError else { return String(describing: type(of: error)) }
+  switch urlError.code {
+  case .notConnectedToInternet: return "not connected to the internet"
+  case .timedOut: return "timed out"
+  case .cannotFindHost, .dnsLookupFailed: return "host not found"
+  case .cannotConnectToHost: return "connection refused"
+  case .networkConnectionLost: return "connection lost"
+  case .secureConnectionFailed, .serverCertificateUntrusted, .serverCertificateHasBadDate,
+    .serverCertificateNotYetValid, .serverCertificateHasUnknownRoot:
+    return "TLS failure"
+  default: return "URLError \(urlError.code.rawValue)"
+  }
+}