@advenue/react-native 0.9.0 → 1.0.1

package/ios/vendor/AdvenuePlatform/HttpTransport.swift

@@ -0,0 +1,96 @@
+import Foundation
+
+/// What the SDK POSTs. `apiKey` travels in the body, matching
+/// `eventBatchSchema`.
+struct EventBatch: Encodable {
+  let apiKey: String
+  let events: [ClientEvent]
+}
+
+public let DEFAULT_ENDPOINT = "https://ingest.advenue.io"
+/// The schema caps a batch at 100 events.
+
+/// Batched ingest over URLSession.
+///
+/// Throws `IngestError` on a non-2xx so the caller can distinguish a transient
+/// failure from a poison payload; a transport failure maps to 408, matching
+/// sdk-core so both SDKs retry exactly the same cases.
+public struct HttpTransport: EventTransport, Sendable {
+  private let endpoint: String
+  private let apiKey: String
+  private let signingSecret: String?
+  private let signer: any Signer
+  private let clock: any Clock
+  private let session: URLSession
+  /// Receives the app the server reported for an ACCEPTED batch. Purely
+  /// diagnostic: it runs after the batch is already accepted, so nothing it
+  /// does can turn a successful ingest into a failure.
+  private let onAccepted: @Sendable (String) -> Void
+
+  public init(
+    endpoint: String = DEFAULT_ENDPOINT,
+    apiKey: String,
+    signingSecret: String? = nil,
+    signer: any Signer = CryptoKitSigner(),
+    clock: any Clock = SystemClock(),
+    session: URLSession = .shared,
+    onAccepted: @escaping @Sendable (String) -> Void = { _ in }
+  ) {
+    self.onAccepted = onAccepted
+    self.endpoint = endpoint
+    self.apiKey = apiKey
+    self.signingSecret = signingSecret
+    self.signer = signer
+    self.clock = clock
+    self.session = session
+  }
+
+  /// The exact request this transport would send. Public so a test can assert
+  /// 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 {
+    let body = try EventEncoding.canonicalEncoder()
+      .encode(EventBatch(apiKey: apiKey, events: events))
+    var request = URLRequest(url: URL(string: "\(endpoint)/v1/events")!)
+    request.httpMethod = "POST"
+    request.setValue("application/json", forHTTPHeaderField: "content-type")
+    request.httpBody = body
+    request.timeoutInterval = 15
+
+    if let secret = signingSecret {
+      let timestamp = String(clock.nowMs())
+      request.setValue(timestamp, forHTTPHeaderField: "X-Advenue-Timestamp")
+      request.setValue(
+        signRequest(
+          signer, secret: secret, timestamp: timestamp,
+          body: String(decoding: body, as: UTF8.self)),
+        forHTTPHeaderField: "X-Advenue-Signature")
+    }
+    return request
+  }
+
+  public func send(_ events: [ClientEvent]) async throws {
+    let request = try buildRequest(events)
+    let response: URLResponse
+    let payload: Data
+    do {
+      (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)
+    }
+    guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
+    guard (200..<300).contains(http.statusCode) else {
+      throw IngestError(status: http.statusCode)
+    }
+
+    // Diagnostics only — the batch is already accepted at this point, so a
+    // missing or unparseable body must change nothing.
+    if let body = try? JSONSerialization.jsonObject(with: payload) as? [String: Any],
+      let appId = body["appId"] as? String, !appId.isEmpty
+    {
+      onAccepted(appId)
+    }
+  }
+}

package/ios/vendor/AdvenuePlatform/Identity.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+/// Survives uninstall — Keychain.
+public let DEVICE_ID_KEY = "advenue.device_id"
+/// Dies with the app — UserDefaults.
+public let INSTALLATION_ID_KEY = "advenue.installation_id"
+
+public enum IdentityResolution: Equatable, Sendable {
+  case resolved(deviceId: String, installationId: String)
+  /// The Keychain could not be read. The caller waits for
+  /// `protectedDataDidBecomeAvailable` rather than inventing an identity.
+  case deferred
+}
+
+/// Resolves the pair the SDK stamps on every event.
+///
+/// The asymmetry is the design: `device_id` lives in the Keychain and survives
+/// uninstall, `installation_id` lives in UserDefaults and does not. Reinstall
+/// detection rests entirely on that difference, so neither half may quietly
+/// move to the other store.
+///
+/// A locked Keychain returns `.deferred` and mints nothing. Treating it as
+/// absent is what would stamp a whole background launch with a device id
+/// belonging to no real device — reachable since #26 introduced silent push,
+/// which can start the app before the first unlock after a reboot.
+public func resolveIdentity(
+  secure: any SecureStore,
+  store: any KeyValueStore,
+  uuid: any UUIDSource
+) -> IdentityResolution {
+  let deviceId: String
+  switch secure.read(DEVICE_ID_KEY) {
+  case .found(let existing):
+    deviceId = existing
+  case .unavailable:
+    return .deferred
+  case .absent:
+    let minted = uuid.next()
+    secure.write(minted, forKey: DEVICE_ID_KEY)
+    deviceId = minted
+  }
+
+  let installationId: String
+  if let existing = store.string(forKey: INSTALLATION_ID_KEY) {
+    installationId = existing
+  } else {
+    installationId = uuid.next()
+    store.set(installationId, forKey: INSTALLATION_ID_KEY)
+  }
+
+  return .resolved(deviceId: deviceId, installationId: installationId)
+}

package/ios/vendor/AdvenuePlatform/InstallEnrichment.swift

@@ -0,0 +1,155 @@
+import CryptoKit
+import Foundation
+
+/// Spec §5: the install waits this long for enrichment and no longer. Matches
+/// the deadlines the RN SDK already uses (SKAN config 3000 ms).
+public let INSTALL_WINDOW_MS = 3_000
+
+/// What the install event carries beyond the envelope every event has.
+public struct Enrichment: Sendable, Equatable {
+  public var attestation: AttestationResult?
+  public var attestationChallenge: String?
+  public var idfa: String?
+  public var vendorId: String?
+  public var appInstanceId: String?
+  public var adservicesToken: String?
+  /// B2: reklam takibi sınırlama bayrağı — düşürülüyordu, artık olaya işlenir.
+  public var limitAdTracking: Bool
+
+  public init(
+    idfa: String? = nil, vendorId: String? = nil,
+    appInstanceId: String? = nil, adservicesToken: String? = nil,
+    attestation: AttestationResult? = nil, attestationChallenge: String? = nil,
+    limitAdTracking: Bool = false
+  ) {
+    self.attestation = attestation
+    self.attestationChallenge = attestationChallenge
+    self.idfa = idfa
+    self.vendorId = vendorId
+    self.appInstanceId = appInstanceId
+    self.adservicesToken = adservicesToken
+    self.limitAdTracking = limitAdTracking
+  }
+}
+
+/// The capabilities the collector draws on, injected so the deadline behaviour
+/// is testable without ATT, AdServices or Firebase — none of which a simulator
+/// can exercise.
+public struct EnrichmentSources: Sendable {
+  public var searchAdsToken: @Sendable () async -> String?
+  public var advertisingId: @Sendable () -> (idfa: String?, vendorId: String?)
+  /// B2: ATT sınırlama bayrağı. Ayrı kapanış — advertisingId demetini
+  /// değiştirmek mevcut sahte kaynakları kırardı.
+  public var limitAdTracking: @Sendable () -> Bool
+  public var appInstanceId: @Sendable () async -> String?
+  /// Returns the attested challenge and its result, or nil. Every failure path
+  /// — unsupported device, challenge fetch, attest — yields nil, because an
+  /// install held for attestation is an install lost.
+  public var attestation: @Sendable () async -> (challenge: String, result: AttestationResult)?
+
+  public init(
+    searchAdsToken: @escaping @Sendable () async -> String?,
+    advertisingId: @escaping @Sendable () -> (idfa: String?, vendorId: String?),
+    appInstanceId: @escaping @Sendable () async -> String?,
+    attestation: @escaping @Sendable () async -> (challenge: String, result: AttestationResult)? = {
+      nil
+    },
+    limitAdTracking: @escaping @Sendable () -> Bool = { false }
+  ) {
+    self.searchAdsToken = searchAdsToken
+    self.advertisingId = advertisingId
+    self.appInstanceId = appInstanceId
+    self.attestation = attestation
+    self.limitAdTracking = limitAdTracking
+  }
+
+  /// Production wiring. `AdvertisingIdentity.advertisingId` already returns nil
+  /// unless ATT is authorized, so the SDK never ships the zero UUID — which
+  /// would be worse than nothing, because it looks like an identifier.
+  public static func system(
+    appInstanceIdProvider: (@Sendable () async -> String?)? = nil,
+    attestation: (@Sendable () async -> (challenge: String, result: AttestationResult)?)? = nil
+  ) -> EnrichmentSources {
+    EnrichmentSources(
+      searchAdsToken: { await SearchAdsTokenFetcher().token() },
+      advertisingId: {
+        let identity = AdvertisingIdentity()
+        return (idfa: identity.advertisingId, vendorId: identity.vendorId)
+      },
+      appInstanceId: { await appInstanceIdProvider?() },
+      attestation: { await attestation?() },
+      limitAdTracking: { AdvertisingIdentity().limitAdTracking })
+  }
+}
+
+/// Collects what is ready before `deadlineMs` and returns; a source still
+/// running when the deadline expires contributes nothing.
+///
+/// The deadline is hard by design (spec §5). The AdServices retry can still be
+/// in flight when it expires, and the install is sent regardless: a token that
+/// arrives afterwards rides the next event, whereas a delayed install shifts
+/// every attribution window behind it.
+public func collectEnrichment(
+  _ sources: EnrichmentSources,
+  deadlineMs: Int
+) async -> Enrichment {
+  // Synchronous reads; no reason to race them.
+  let ids = sources.advertisingId()
+  var result = Enrichment(
+    idfa: ids.idfa, vendorId: ids.vendorId,
+    limitAdTracking: sources.limitAdTracking())
+
+  await withTaskGroup(of: (String, String?).self) { group in
+    group.addTask { ("adservices", await sources.searchAdsToken()) }
+    group.addTask { ("appInstance", await sources.appInstanceId()) }
+    group.addTask {
+      try? await Task.sleep(nanoseconds: UInt64(deadlineMs) * 1_000_000)
+      return ("deadline", nil)
+    }
+
+    var settled = 0
+    for await (key, value) in group {
+      if key == "deadline" { break }
+      if key == "adservices" { result.adservicesToken = value }
+      if key == "appInstance" { result.appInstanceId = value }
+      settled += 1
+      if settled == 2 { break }
+    }
+    group.cancelAll()
+  }
+
+  // Attestation is two round trips — challenge, then attest — and is raced by
+  // the same deadline as everything else. An `async let` awaited here would
+  // NOT be bounded: it would hold the install for as long as Apple took, which
+  // is the one thing enrichment must never do.
+  if let attested = await withDeadline(ms: deadlineMs, { await sources.attestation() }) {
+    result.attestation = attested?.result
+    result.attestationChallenge = attested?.challenge
+  }
+
+  return result
+}
+
+/// Runs `work` and gives up at the deadline. Returns nil when the deadline won,
+/// which the caller treats the same as "the source had nothing".
+func withDeadline<T: Sendable>(
+  ms: Int, _ work: @escaping @Sendable () async -> T
+) async -> T? {
+  await withTaskGroup(of: Optional<T>.self) { group in
+    group.addTask { await work() }
+    group.addTask {
+      try? await Task.sleep(nanoseconds: UInt64(ms) * 1_000_000)
+      return nil
+    }
+    let first = await group.next() ?? nil
+    group.cancelAll()
+    return first
+  }
+}
+
+
+/// Lowercase hex SHA-256. Used for the Meta AEM `sourceUrlHash`, which both the
+/// SDK and the server dedup on, so the two must agree byte for byte.
+public func sha256Hex(_ value: String) -> String {
+  SHA256.hash(data: Data(value.utf8)).map { String(format: "%02x", $0) }.joined()
+}

package/ios/vendor/AdvenuePlatform/KeychainStore.swift

@@ -0,0 +1,95 @@
+import Foundation
+import Security
+
+/// The answer to a secure read. The three cases are genuinely different, and
+/// collapsing `unavailable` into `absent` is the bug this type exists to
+/// prevent.
+public enum SecureReadResult: Equatable, Sendable {
+  /// A value is stored and readable.
+  case found(String)
+  /// No such item. A caller may mint a new identity.
+  case absent
+  /// The item exists or may exist, but it cannot be read —
+  /// `errSecInteractionNotAllowed` on an `AfterFirstUnlock` item before the
+  /// first unlock after a reboot. A caller MUST NOT mint a new identity:
+  /// silent push can background-launch the app in exactly this window, and a
+  /// fresh device id there means a phantom device and a phantom install.
+  case unavailable
+}
+
+/// Storage that survives app uninstall. `device_id` lives here; the
+/// installation id and install flag live in UserDefaults precisely because
+/// they must NOT survive — reinstall detection rests on that asymmetry.
+public protocol SecureStore: Sendable {
+  func read(_ key: String) -> SecureReadResult
+  func write(_ value: String, forKey key: String)
+  func delete(_ key: String)
+}
+
+public struct KeychainStore: SecureStore {
+  /// Shared with the App Attest key id under a different account, matching the
+  /// RN module. Same service, distinct accounts, so neither can read the
+  /// other's entry.
+  public static let service = "io.advenue.sdk"
+
+  public init() {}
+
+  private func baseQuery(_ key: String) -> [String: Any] {
+    [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: Self.service,
+      kSecAttrAccount as String: key,
+    ]
+  }
+
+  /// Maps a Keychain result to the three answers the SDK distinguishes.
+  ///
+  /// Split out as a pure function because it is the part that decides whether
+  /// a device id gets invented, and it is testable without Keychain access —
+  /// which an unsigned XCTest bundle in the simulator does not have
+  /// (`errSecMissingEntitlement`). The round-trip needs a signed host app or a
+  /// real device; this decision does not, and it is where the bug was.
+  public static func interpret(status: OSStatus, data: Data?) -> SecureReadResult {
+    switch status {
+    case errSecSuccess:
+      guard let data, let value = String(data: data, encoding: .utf8) else { return .absent }
+      return .found(value)
+    case errSecItemNotFound:
+      return .absent
+    default:
+      // errSecInteractionNotAllowed (locked), errSecMissingEntitlement, and
+      // every other error land here. Treating any of them as "no value" is
+      // what would invent a device.
+      return .unavailable
+    }
+  }
+
+  public func read(_ key: String) -> SecureReadResult {
+    var query = baseQuery(key)
+    query[kSecReturnData as String] = true
+    query[kSecMatchLimit as String] = kSecMatchLimitOne
+    var result: AnyObject?
+    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    return Self.interpret(status: status, data: result as? Data)
+  }
+
+  public func write(_ value: String, forKey key: String) {
+    guard let data = value.data(using: .utf8) else { return }
+    let base = baseQuery(key)
+    let status = SecItemUpdate(
+      base as CFDictionary, [kSecValueData as String: data] as CFDictionary)
+    if status == errSecItemNotFound {
+      var add = base
+      add[kSecValueData as String] = data
+      // AfterFirstUnlock so a background launch after reboot can read it;
+      // ThisDeviceOnly so an iCloud restore cannot put one device's identity
+      // on another, which would merge two devices into one.
+      add[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+      SecItemAdd(add as CFDictionary, nil)
+    }
+  }
+
+  public func delete(_ key: String) {
+    SecItemDelete(baseQuery(key) as CFDictionary)
+  }
+}

package/ios/vendor/AdvenuePlatform/SearchAdsToken.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+#if canImport(AdServices)
+  import AdServices
+#endif
+
+public enum SearchAdsError: Error, Sendable {
+  /// Retrying may succeed — the token is often unavailable for a few seconds
+  /// after install.
+  case transient
+  /// Retrying cannot help.
+  case unsupported
+}
+
+/// Fetches the Apple Search Ads attribution token, retrying transient
+/// failures.
+///
+/// `AAAttribution.attributionToken()` can fail immediately after install;
+/// field reports put the transient internal error at roughly 8% of users. The
+/// RN module calls it once and rejects on any throw, so those installs
+/// silently become organic and Apple Search Ads spend goes unattributed.
+///
+/// The retry deliberately outlives the caller's first-open deadline: the
+/// install is never held for it, and a token obtained on a later attempt
+/// travels on the next event. Holding the install instead would shift
+/// attribution windows, which is worse than a less enriched install.
+public struct SearchAdsTokenFetcher: Sendable {
+  private let attempts: Int
+  private let delayMs: Int
+  private let fetch: @Sendable () throws -> String
+
+  public init(
+    attempts: Int = 3,
+    delayMs: Int = 1000,
+    fetch: (@Sendable () throws -> String)? = nil
+  ) {
+    self.attempts = attempts
+    self.delayMs = delayMs
+    self.fetch = fetch ?? Self.systemFetch
+  }
+
+  @Sendable
+  private static func systemFetch() throws -> String {
+    #if canImport(AdServices)
+      if #available(iOS 14.3, *) {
+        do {
+          return try AAAttribution.attributionToken()
+        } catch {
+          throw SearchAdsError.transient
+        }
+      }
+      throw SearchAdsError.unsupported
+    #else
+      throw SearchAdsError.unsupported
+    #endif
+  }
+
+  public func token() async -> String? {
+    for attempt in 1...attempts {
+      do {
+        return try fetch()
+      } catch SearchAdsError.unsupported {
+        return nil
+      } catch {
+        guard attempt < attempts else { return nil }
+        // 1 s, 2 s, 4 s — long enough for the system to settle, bounded so a
+        // permanently broken device does not retry forever.
+        let backoff = delayMs * (1 << (attempt - 1))
+        if backoff > 0 {
+          try? await Task.sleep(nanoseconds: UInt64(backoff) * 1_000_000)
+        }
+      }
+    }
+    return nil
+  }
+}

package/ios/vendor/AdvenuePlatform/SkanConfigFetcher.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// Matches the deadline the RN SDK uses. The install does not wait for this
+/// beyond it — a config that arrives late applies to the next event.
+public let SKAN_CONFIG_TIMEOUT_MS = 3_000
+
+/// Fetches the conversion-value config the dashboard serves.
+///
+/// This is what makes SKAN configurable at all: a conversion schema is tuned
+/// constantly and an app release cycle is weeks, so a config that can only be
+/// changed by shipping a new binary is a config nobody changes.
+public struct HttpSkanConfigFetcher: SkanConfigSource {
+  private let endpoint: String
+  private let apiKey: String
+  private let session: URLSession
+
+  public init(
+    endpoint: String = DEFAULT_ENDPOINT, apiKey: String, session: URLSession = .shared
+  ) {
+    self.endpoint = endpoint
+    self.apiKey = apiKey
+    self.session = session
+  }
+
+  public func fetch(etag: String?) async throws -> SkanConfigResult {
+    var request = URLRequest(url: URL(string: "\(endpoint)/v1/sdk-config")!)
+    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
+    if let etag { request.setValue(etag, forHTTPHeaderField: "if-none-match") }
+    request.timeoutInterval = Double(SKAN_CONFIG_TIMEOUT_MS) / 1000
+
+    let (payload, response) = try await session.data(for: request)
+    guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
+    if http.statusCode == 304 { return .notModified }
+    guard (200..<300).contains(http.statusCode) else {
+      throw IngestError(status: http.statusCode)
+    }
+
+    guard let body = try? JSONSerialization.jsonObject(with: payload) as? [String: Any],
+      let version = body["version"] as? Int, version >= 0,
+      let skan = body["skan"] as? [String: Any]
+    else { throw IngestError(status: 422) }
+
+    return .fetched(
+      RemoteSkanConfig(
+        version: version,
+        rules: try decodeRules(skan),
+        etag: http.value(forHTTPHeaderField: "etag")))
+  }
+
+  /// Decoded by hand rather than through Codable: the server's shape is a JSON
+  /// object the dashboard writes, and a decoding failure must be an ordinary
+  /// rejected config rather than an exception nobody catches.
+  private func decodeRules(_ raw: [String: Any]) throws -> ConversionValueConfig {
+    let rawRules = raw["rules"] as? [[String: Any]] ?? []
+    let rules: [ConversionValueRule] = rawRules.compactMap { rule in
+      guard let fine = rule["fineValue"] as? Int else { return nil }
+      return ConversionValueRule(
+        fineValue: fine,
+        coarseValue: (rule["coarseValue"] as? String).flatMap(CoarseValue.init(rawValue:)),
+        minRevenueMicros: rule["minRevenueMicros"] as? String,
+        events: rule["events"] as? [String])
+    }
+    guard rules.count == rawRules.count else { throw IngestError(status: 422) }
+
+    return ConversionValueConfig(
+      rules: rules,
+      defaultCoarse: (raw["defaultCoarse"] as? String).flatMap(CoarseValue.init(rawValue:)),
+      revenueCurrency: raw["revenueCurrency"] as? String)
+  }
+}

package/ios/vendor/AdvenuePlatform/StoreKitSkanReporter.swift

@@ -0,0 +1,140 @@
+import Foundation
+
+#if os(iOS)
+  import StoreKit
+
+  #if canImport(AdAttributionKit)
+    import AdAttributionKit
+  #endif
+#endif
+
+/// SKAdNetwork through StoreKit.
+///
+/// Three API generations, and an OS with none of them must do nothing rather
+/// than trap: an SDK that crashes on an old device takes the host app down with
+/// it, and SKAN is the least important thing it does.
+///
+/// On macOS — where the host test suite runs — SKAdNetwork does not exist at
+/// all, so this degrades to nothing. `canImport(StoreKit)` is the wrong gate
+/// and compiles happily before failing on the symbol: StoreKit is there, SKAN
+/// is not.
+///
+/// **What a simulator does here, measured rather than assumed:** it does NOT
+/// silently succeed. `updatePostbackConversionValue` answers
+/// `SKANErrorDomain 10` when there is no ad impression to attach a value to,
+/// which is also what a real device with no impression does. So the simulator
+/// exercises the SDK's degradation path for real — the caller abandons the
+/// value and reports it — and that is worth more than the no-op this comment
+/// originally claimed.
+///
+/// What it still cannot settle is the success path: that a postback arrives
+/// carrying the value we sent needs a device with a signed impression, and it
+/// is on the checklist rather than implied here.
+public struct StoreKitSkanReporter: SkanReporter {
+  private let onError: @Sendable (String, any Error) -> Void
+  private let adAttributionUpdate: @Sendable (Int, CoarseValue, Bool) async throws -> Void
+
+  public init(
+    onError: @escaping @Sendable (String, any Error) -> Void = { _, _ in },
+    adAttributionUpdate: (@Sendable (Int, CoarseValue, Bool) async throws -> Void)? = nil
+  ) {
+    self.onError = onError
+    self.adAttributionUpdate = adAttributionUpdate ?? Self.systemAdAttributionUpdate
+  }
+
+  /// AdAttributionKit, iOS 17.4+. An impression may be signed for either rail,
+  /// so both are updated rather than one chosen.
+  ///
+  /// Injectable because the invariant that matters cannot otherwise be tested:
+  /// a failure here is **expected** whenever no AAK-signed impression exists,
+  /// and it must not fail the SKAN update. If it did, a device with only a
+  /// SKAN-signed impression would never confirm its value and that window would
+  /// report nothing for the rest of its life.
+  @Sendable
+  private static func systemAdAttributionUpdate(
+    fine: Int, coarse: CoarseValue, lockWindow: Bool
+  ) async throws {
+    #if os(iOS) && canImport(AdAttributionKit)
+      if #available(iOS 17.4, *) {
+        try await Postback.updateConversionValue(
+          fine, coarseConversionValue: coarse.adAttributionValue,
+          lockPostback: lockWindow)
+      }
+    #endif
+  }
+
+  public func register() {
+    #if os(iOS)
+      if #available(iOS 16.1, *) {
+        // The modern form registers implicitly on the first conversion update,
+        // but calling it explicitly is what starts the window for an install
+        // that never converts — which is most of them.
+        SKAdNetwork.updatePostbackConversionValue(0) { error in
+          if let error { onError("skan.register", error) }
+        }
+      } else if #available(iOS 14.0, *) {
+        SKAdNetwork.registerAppForAdNetworkAttribution()
+      }
+    #endif
+  }
+
+  public func update(fine: Int, coarse: CoarseValue, lockWindow: Bool) async throws {
+    // AdAttributionKit first, and its failure is swallowed on purpose: it is
+    // the expected answer when no AAK-signed impression exists. Letting it
+    // propagate would abandon a perfectly good SKAN value.
+    do {
+      try await adAttributionUpdate(fine, coarse, lockWindow)
+    } catch {
+      onError("skan.adAttributionKit", error)
+    }
+
+    #if os(iOS)
+      if #available(iOS 16.1, *) {
+        try await SKAdNetwork.updatePostbackConversionValue(
+          fine, coarseValue: coarse.storeKitValue, lockWindow: lockWindow)
+        return
+      }
+      if #available(iOS 15.4, *) {
+        // No coarse value before 16.1. Sending the fine value alone is still
+        // worth doing: v3-signed ads read it.
+        try await SKAdNetwork.updatePostbackConversionValue(fine)
+        return
+      }
+      if #available(iOS 14.0, *) {
+        SKAdNetwork.updateConversionValue(fine)
+        return
+      }
+    #endif
+    // No SKAN on this OS. Not an error worth surfacing — there is nothing the
+    // app or the SDK could do about it.
+  }
+}
+
+#if os(iOS) && canImport(AdAttributionKit)
+  extension CoarseValue {
+    /// AdAttributionKit's own enum, distinct from StoreKit's.
+    @available(iOS 17.4, *)
+    var adAttributionValue: AdAttributionKit.CoarseConversionValue {
+      switch self {
+      case .low: return .low
+      case .medium: return .medium
+      case .high: return .high
+      }
+    }
+  }
+#endif
+
+#if os(iOS)
+  extension CoarseValue {
+    /// Apple's own enum. Mapping this wrong silently files every postback in
+    /// the wrong bucket, and nothing downstream can detect it.
+    @available(iOS 16.1, *)
+    var storeKitValue: SKAdNetwork.CoarseConversionValue {
+      switch self {
+      case .low: return .low
+      case .medium: return .medium
+      case .high: return .high
+      }
+    }
+  }
+#endif