@advenue/react-native 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -54,9 +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. */
@@ -69,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;
 }
 
@@ -80,7 +95,6 @@ type TrackingAuthorizationStatus = 'authorized' | 'denied' | 'restricted' | 'not
 interface BridgeInitOptions {
     apiKey: string;
     endpoint?: string;
-    appVersion?: string;
     requireConsent: boolean;
     batchSize?: number;
     flushIntervalMs?: number;

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.0",
+  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",
@@ -203,11 +203,18 @@ function getLinking() {
 }
 
 // src/index.ts
-var IGNORED_OPTIONS = ["mmkv", "secureStore", "sdkConfigFetcher", "tcfDataCollection"];
+var IGNORED_OPTIONS = [
+  "mmkv",
+  "secureStore",
+  "sdkConfigFetcher",
+  "tcfDataCollection",
+  "appVersion"
+];
 var started = false;
 var deepLinkSub = null;
 var errorSub = null;
 var onErrorHook;
+var debugLogging = false;
 var consentCache = false;
 function bridge() {
   return { ios: getIosNative(), android: getAndroidNative() };
@@ -232,6 +239,7 @@ function report(context, cause) {
     onErrorHook?.(context, cause);
   } catch {
   }
+  if (debugLogging) console.warn(`[Advenue] ${context}`, cause);
 }
 function requireStarted() {
   if (started) return true;
@@ -245,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(
@@ -257,14 +266,17 @@ var Advenue = {
     call("bridgeInitialize", {
       apiKey: config.apiKey,
       endpoint: config.endpoint,
-      appVersion: config.appVersion,
       requireConsent: config.requireConsent ?? false,
       batchSize: config.batchSize,
       flushIntervalMs: config.flushIntervalMs,
       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

@@ -37,7 +37,6 @@ public class AdvenueIosModule: Module {
       var config = AdvenueConfig(
         apiKey: app,
         endpoint: (options["endpoint"] as? String) ?? DEFAULT_ENDPOINT,
-        appVersion: options["appVersion"] as? String,
         requireConsent: (options["requireConsent"] as? Bool) ?? false,
         signingSecret: options["signingSecret"] as? String,
         onError: { [weak self] context, error in
@@ -45,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
   }
 }
 
@@ -208,12 +209,34 @@ final class FacadeState: @unchecked Sendable {
     _ config: AdvenueConfig,
     transport: (any EventTransport)? = nil,
     sources: EnrichmentSources? = nil,
-    skan skanReporter: (any SkanReporter)? = nil
+    skan skanReporter: (any SkanReporter)? = nil,
+    appVersion readVersion: () -> String? = readAppVersion,
+    launchedInBackground: () -> Bool = readLaunchedInBackground,
+    logSink: (any AdvenueLogSink)? = nil
   ) {
     // Replace-and-shut-down, never add.
     stop()
 
-    let store = UserDefaultsStore()
+    // `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", AdvenueSetupError.appVersionIgnored)
+    }
+
+    // B4: kuyruk blob'u Caches dosyalarına (yedek dışı); UserDefaults'ta
+    // kalan eski blob ilk okumada migrate edilir. Caches yoksa UserDefaults
+    // geri dönüşüdür — yedek kapsamı açılır ama SDK çalışır (fail-open, loglanır).
+    let store: any KeyValueStore
+    if let files = CacheFileStore.caches() {
+      store = CompositeStore(files: files)
+    } else {
+      store = UserDefaultsStore()
+      config.onError("store.cache_unavailable", AdvenueSetupError.cacheUnavailable)
+    }
     let secure = KeychainStore()
     let uuid = SystemUUIDs()
 
@@ -222,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
     }
 
@@ -233,19 +256,24 @@ 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(
         apiKey: config.apiKey, platform: "ios", deviceId: deviceId,
-        installationId: installationId, appVersion: config.appVersion,
+        installationId: installationId, appVersion: readVersion(),
         osVersion: osVersion,
         sdkVersion: String((config.sdkVersion ?? AdvenueVersion.current).prefix(32)),
         requireConsent: config.requireConsent, sessionWindowMs: config.sessionWindowMs,
@@ -312,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))
@@ -357,7 +404,8 @@ final class FacadeState: @unchecked Sendable {
       self?.submit(
         .setIdentity(
           idfa: enrichment.idfa, vendorId: enrichment.vendorId,
-          appInstanceId: enrichment.appInstanceId))
+          appInstanceId: enrichment.appInstanceId,
+          limitAdTracking: enrichment.limitAdTracking))
       self?.submit(.setDeviceInfo(collectDeviceInfo()))
       // The CMP writes TCF to the standard defaults, and reading it is the
       // difference between shipping a real consent signal and shipping none.
@@ -487,10 +535,27 @@ final class FacadeState: @unchecked Sendable {
     return pendingDeepLinks.count
   }
 
+  /// B3: deep-link URL'sinden query+fragment atılır. URLComponents
+  /// çözümlenemezse ham dizenin `?`/`#` öncesi alınır (asla ham query sızmaz).
+  func stripUrlQuery(_ url: URL) -> String {
+    if var components = URLComponents(url: url, resolvingAgainstBaseURL: false) {
+      components.query = nil
+      components.fragment = nil
+      if let stripped = components.string { return stripped }
+    }
+    let raw = url.absoluteString
+    if let cut = raw.firstIndex(where: { $0 == "?" || $0 == "#" }) {
+      return String(raw[..<cut])
+    }
+    return raw
+  }
+
   private func send(_ url: URL) {
+    // B3: ham query gönderilmez — token/e-posta query'de taşınır. AEM
+    // ayrıştırması ve hash TAM url'den yapılır (aşağıda).
     submit(
       .track(
-        name: "deep_link", properties: ["url": .string(url.absoluteString)], type: "custom"))
+        name: "deep_link", properties: ["url": .string(stripUrlQuery(url))], type: "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 same
@@ -557,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

@@ -3,6 +3,8 @@ import Foundation
 public struct AdvenueConfig: Sendable {
   public var apiKey: String
   public var endpoint: String
+  /// Ignored: the SDK reads the app version from the bundle itself. Setting it
+  /// reports `config.ignored:appVersion` through `onError`. Removed in the next major.
   public var appVersion: String?
   public var requireConsent: Bool
   public var sessionWindowMs: Int64
@@ -27,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.
   ///
@@ -41,6 +49,12 @@ public struct AdvenueConfig: Sendable {
   /// the whole batch down with a 400, so it is truncated rather than sent.
   public var sdkVersion: String?
 
+  /// B5: `https://` şema kuralı. Fail-fast `precondition` ile kurulumda
+  /// yakalanır; kuralın kendisi test edilebilir saf fonksiyondur.
+  public static func isSecureEndpoint(_ endpoint: String) -> Bool {
+    endpoint.lowercased().hasPrefix("https://")
+  }
+
   public init(
     apiKey: String,
     endpoint: String = DEFAULT_ENDPOINT,
@@ -52,12 +66,18 @@ public struct AdvenueConfig: Sendable {
     signingSecret: String? = nil,
     conversionValues: ConversionValueConfig? = nil,
     onError: @escaping @Sendable (String, any Error) -> Void = { _, _ in },
-    sdkVersion: String? = nil
+    sdkVersion: String? = nil,
+    allowInsecureHttp: Bool = false,
+    debug: Bool = false
   ) {
+    precondition(
+      allowInsecureHttp || Self.isSecureEndpoint(endpoint),
+      "Advenue endpoint must use https:// (allowInsecureHttp is test-only)")
     self.apiKey = apiKey
     self.endpoint = endpoint
     self.appVersion = appVersion
     self.requireConsent = requireConsent
+    self.debug = debug
     self.sessionWindowMs = sessionWindowMs
     self.batchSize = batchSize
     self.flushIntervalMs = flushIntervalMs
@@ -73,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