Publish Score iOS SDK 0.3.0

Sources/ScoreTracker/ScoreClient.swift

@@ -7,14 +7,49 @@ import ScoreTrackerKit
 /// and persistent `anonymousId` are handled natively (NSUserDefaults) — see #176.
 public final class ScoreClient {
 
-    private let tracker: ScoreTracker
+    let tracker: ScoreTracker
     private var autoFlushTask: Task<Void, Never>?
+    /// Set while `bindToAppLifecycle()` is in effect (AppLifecycle.swift, #484).
+    var appBindings: AppBindings?
 
     /// - Parameters:
     ///   - endpoint: middleware base URL; events POST to `<endpoint>/api/tracking/website`.
     ///   - initialConsent: defaults to "none" — nothing fires until `setConsent(...)`.
     ///   - pii: field-level PII handling (#482), scrubbed before events are queued on the device.
+    ///   - tokenRefreshTimeoutSeconds: how long a flush waits for the token provider (#483).
+    ///
+    /// The envelope's `sdk.name` / `sdk.version` are baked into the framework
+    /// (#486); there is nothing to pass.
     public init(
+        publishableKey: String,
+        siteId: String,
+        endpoint: String,
+        appVersion: String? = nil,
+        os: String? = nil,
+        device: String? = nil,
+        locale: String? = nil,
+        initialConsent: ConsentState = ConsentState.companion.NONE,
+        pii: PiiOptions? = nil,
+        tokenRefreshTimeoutSeconds: Double = 5
+    ) {
+        let config = TrackerConfig(
+            publishableKey: publishableKey,
+            siteId: siteId,
+            endpoint: endpoint,
+            device: DeviceDescriptor(os: os, device: device, appVersion: appVersion, locale: locale)
+        )
+        tracker = IosPlatformKt.doNewScoreTracker(
+            config: config,
+            initialConsent: initialConsent,
+            pii: pii,
+            tokenRefreshTimeoutMs: Int64(tokenRefreshTimeoutSeconds * 1000)
+        )
+    }
+
+    /// The pre-#486 signature. `sdkVersion` is ignored: the SDK reports the
+    /// version it was built as.
+    @available(*, deprecated, message: "The SDK reports its own version now (#486); sdkVersion is ignored. Drop the argument.")
+    public convenience init(
         publishableKey: String,
         siteId: String,
         endpoint: String,
@@ -26,16 +61,17 @@ public final class ScoreClient {
         initialConsent: ConsentState = ConsentState.companion.NONE,
         pii: PiiOptions? = nil
     ) {
-        let config = TrackerConfig(
-            publishableKey: publishableKey,
-            siteId: siteId,
-            endpoint: endpoint,
-            sdk: SdkInfo(name: "@3halves-labs/score-tracker-ios", version: sdkVersion),
-            device: DeviceDescriptor(os: os, device: device, appVersion: appVersion, locale: locale)
+        self.init(
+            publishableKey: publishableKey, siteId: siteId, endpoint: endpoint,
+            appVersion: appVersion, os: os, device: device, locale: locale,
+            initialConsent: initialConsent, pii: pii
         )
-        tracker = IosPlatformKt.doNewScoreTracker(config: config, initialConsent: initialConsent, pii: pii)
     }
 
+    /// What this build reports as `sdk.name` / `sdk.version` — for support and logs.
+    public static var sdkName: String { SdkInfo.companion.CURRENT.name }
+    public static var sdkVersion: String { SdkInfo.companion.CURRENT.version }
+
     // MARK: - Consent (wire to your CMP / OneTrust)
 
     public func setConsent(analytics: Bool, personalization: Bool, advertising: Bool) {
@@ -51,9 +87,21 @@ public final class ScoreClient {
     }
     public func setToken(_ token: String?) { tracker.setToken(token: token) }
 
-    /// Provider is consulted before each flush — wire to your Auth0 access token.
-    public func setTokenProvider(_ provider: @escaping () -> String?) {
-        tracker.setTokenProvider(provider: provider)
+    /// Supply the fan's access token on demand — wire to Auth0's
+    /// `credentialsManager.credentials()` (#483). `async`, so a silent refresh
+    /// needs no blocking; a plain synchronous closure works too. Consulted
+    /// before each flush, single-flight. If it throws, returns nil or takes
+    /// longer than the tracker's timeout (5 s), the flush goes ahead with the
+    /// last known token — anonymous if there is none.
+    public func setTokenProvider(_ provider: @escaping () async throws -> String?) {
+        tracker.setCallbackTokenProvider { complete in
+            Task { complete(try? await provider()) }   // a throw counts as "no token"
+        }
+    }
+
+    /// Stop consulting a provider; the last token set stays until replaced.
+    public func clearTokenProvider() {
+        tracker.setCallbackTokenProvider(provider: nil)
     }
 
     public var anonymousId: String { tracker.anonymousId }
@@ -61,16 +109,35 @@ public final class ScoreClient {
 
     // MARK: - Tracking
 
-    /// Track an app event. Returns false if dropped by the consent gate.
+    /// Track a typed loyalty event — the preferred form (#485). `Events` is
+    /// generated from the same schemas as the web and Android trackers, so the
+    /// name and its consent contract (`requires`) are identical on every
+    /// platform. Returns false if dropped by the consent gate.
+    ///
+    ///     score.track(Events.shared.PollVote, props: ["pollId": "motm-r12", "choice": "player_7"])
     @discardableResult
-    public func track(_ name: String, props: [String: Any] = [:]) -> Bool {
-        tracker.track(name: name, props: props, type: .track, requires: [], delivery: .bestEffort)
+    public func track(_ event: EventDefinition, props: [String: Any] = [:], delivery: DeliveryMode = .bestEffort) -> Bool {
+        tracker.track(event: event, props: props, delivery: delivery)
+    }
+
+    /// Track an app event by name, for events not in `Events`. `requires` gates
+    /// it on consent categories — it is dropped unless every one is granted.
+    /// Returns false if dropped by the consent gate.
+    @discardableResult
+    public func track(
+        _ name: String,
+        props: [String: Any] = [:],
+        requires: [ConsentCategory] = [],
+        delivery: DeliveryMode = .bestEffort
+    ) -> Bool {
+        tracker.track(name: name, props: props, type: .track, requires: requires, delivery: delivery)
     }
 
     /// Track an event gated on advertising consent (dropped until granted).
+    /// Shorthand for `track(name, props:, requires: [.advertising])`.
     @discardableResult
     public func trackAdvertising(_ name: String, props: [String: Any] = [:]) -> Bool {
-        tracker.track(name: name, props: props, type: .track, requires: [ConsentCategory.advertising], delivery: .bestEffort)
+        track(name, props: props, requires: [ConsentCategory.advertising])
     }
 
     /// Record an app-screen view.
@@ -91,9 +158,18 @@ public final class ScoreClient {
     public func onForeground() async throws { _ = try await tracker.onForeground() }
     /// Call when network connectivity is regained.
     public func onNetworkAvailable() async throws { _ = try await tracker.onNetworkAvailable() }
+    /// Best-effort flush as the app goes to the background (#484), bounded by
+    /// `budgetSeconds` so it cannot hold up suspension. Returns false if it ran
+    /// out of time; unsent events stay queued. `bindToAppLifecycle()` calls this
+    /// for you.
+    @discardableResult
+    public func onBackground(budgetSeconds: Double = 5) async throws -> Bool {
+        try await tracker.onBackground(budgetMs: Int64(budgetSeconds * 1000)).boolValue
+    }
 
     public func shutdown() async throws {
         stopAutoFlush()
+        await MainActor.run { unbindAppLifecycleFromAnyContext() }
         try await tracker.shutdown()
     }