public-sdks-score/INTEGRATION.md

Mobile SDK — Integration Guide (iOS + Android)

The Score mobile tracker is one Kotlin Multiplatform core shipped as a native iOS framework (ScoreTrackerKit, fronted by the Swift ScoreClient facade) and a native Android AAR. It emits the same event envelope as the web tracker (@3halves-labs/score-tracker), so app events fire challenges/goals identically — see conformance/CONTRACT.md.

---

Install — 0.4.0 beta (public, no auth)

Distributed publicly from 3HL-SCORE/public-sdks-score (#284) — no Gitea token / login required. The iOS XCFramework is a public release asset (mobile-v0.4.0) on that repo; the Android artifacts live in the org's Gitea Maven package registry (anonymous read).

Android — Gradle (public Maven registry)

repositories {
    maven { url = uri("https://git.3halves-labs.com/api/packages/3HL-SCORE/maven") } // public — no credentials
}
dependencies {
    implementation("com.threehalveslabs.scoretracker:shared-android:0.4.0")
}

iOS — CocoaPods (public release asset)

pod 'ScoreTracker',
    :podspec => 'https://git.3halves-labs.com/3HL-SCORE/public-sdks-score/raw/branch/main/ScoreTracker.podspec'

iOS — Swift Package Manager (public git URL)

The SPM package lives at the root of the public public-sdks-score repo, so add it by git URL — no registry config, no login:

// your app's Package.swift
dependencies: [
    .package(url: "https://git.3halves-labs.com/3HL-SCORE/public-sdks-score.git", from: "0.4.0")
],
// target: .product(name: "ScoreTracker", package: "public-sdks-score")

Or in Xcode: File → Add Packages… → paste the URL. The binary ScoreTrackerKit target pulls the XCFramework from the public mobile-v0.4.0 release asset (SPM verifies the checksum) — no ~/.netrc credentials needed. Verified with an anonymous swift package resolve.

iOS — direct XCFramework

Download ScoreTracker-pod.zip from the mobile-v0.4.0 release on public-sdks-score. It holds ScoreTrackerKit.xcframework and the Swift facade sources (Sources/ScoreTracker/: ScoreClient.swift, Exports.swift, AppLifecycle.swift). Drag the .xcframework into your Xcode project and add the Swift files to your app target.

---

iOS (Swift)

import ScoreTracker   // the Swift facade (wraps the ScoreTrackerKit framework)

let score = ScoreClient(
    publishableKey: "pk_live_…",
    siteId: "urc-ios",
    endpoint: "https://<middleware-host>",
    appVersion: Bundle.main.shortVersion,
    os: "iOS \(UIDevice.current.systemVersion)",
    device: UIDevice.current.model,
    locale: Locale.current.identifier
)

// Nothing sends until consent is granted (see Consent below).
score.grantAllConsent()

// Track app earning events with the generated `Events` taxonomy (preferred):
// the wire name and its consent `requires` come from the shared schema, so iOS,
// Android and web emit byte-identical events (#206, #485).
score.track(Events.shared.PollVote, props: ["pollId": "motm-r12", "choice": "player_7"])

// …or by name, for an event not in `Events`. `requires:` gates it on consent.
score.track("custom_badge_tap", props: ["badgeId": "b1"], requires: [.analytics])
score.screen("match_centre")

// Flush is async; the SDK also auto-flushes (see Offline & flushing)
Task { try? await score.flush() }

The envelope's sdk.name and sdk.version are baked into the build: …-ios or …-android from the platform, and the version from the release (#486). There's nothing to pass. Read them with ScoreClient.sdkName / ScoreClient.sdkVersion (Swift) or SdkInfo.CURRENT (Kotlin) when a support conversation asks "which version are you on?". The old sdkVersion: argument and TrackerConfig(…, sdk = …) still compile, but are deprecated and ignored.

The durable offline queue and persistent anonymousId are handled natively (NSUserDefaults) — events survive app cold starts and flush when back online.

Android (Kotlin)

The shared core is already idiomatic Kotlin — no facade needed; construct via the newScoreTracker(context, …) factory (uses SharedPreferences + OkHttp):

import com.threehalveslabs.scoretracker.*

val score = newScoreTracker(
    context = applicationContext,
    config = TrackerConfig(
        publishableKey = "pk_live_…",
        siteId = "urc-android",
        endpoint = "https://<middleware-host>",
        device = DeviceDescriptor(os = "Android ${Build.VERSION.RELEASE}", device = Build.MODEL,
                                  appVersion = BuildConfig.VERSION_NAME, locale = Locale.getDefault().toLanguageTag()),
    ),
)

score.setConsent(ConsentState.ALL)

// Either a string name…
score.track("poll_vote", mapOf("pollId" to "motm-r12", "choice" to "player_7"))
// …or a typed definition from the generated `Events` taxonomy (preferred): the
// wire name + consent `requires` come from the shared schema, so app + web emit
// byte-identical events (#206). Same `Events` exist in the web tracker.
score.track(Events.PollVote, mapOf("pollId" to "motm-r12", "choice" to "player_7"))

// flush()/shutdown() are suspend — call from a coroutine
lifecycleScope.launch { score.flush() }

Events (Events.PollVote, Events.SportsPrediction, Events.SocialShare, Events.ArticleRead, Events.ProductView, Events.VideoWatch, Events.ProfileFavouriteTeam, …) is generated from sdk/schemas/events/*.schema.json via npm run gen:events. Don't edit Events.kt by hand — edit the schema and regenerate; the web-side drift guard keeps it in lockstep.

---

Consent (wire to your CMP / OneTrust)

Mirrors the web tracker (#108): the tracker is idle until consent is granted, and pre-consent events are dropped, not buffered. Update consent whenever the user's CMP choice changes.

// iOS — in your CMP's "consent changed" callback:
score.setConsent(analytics: groups.analytics, personalization: groups.personalization, advertising: groups.advertising)

// Android:
score.setConsent(ConsentState(analytics = a, personalization = p, advertising = ad))

Events declaring a category are dropped until that category is granted. A typed Events definition carries its own (Events.PollVote requires analytics, Events.AdImpression advertising), identically on iOS and Android. For a named event, pass it yourself: requires: [.advertising] on iOS (or the trackAdvertising(...) shorthand), requires = listOf(ConsentCategory.ADVERTISING) on Android.

PII scrubbing

Same options as the web tracker's pii (#482). Scrubbing runs when you call track(), before the event is queued, so a raw value never reaches the on-device queue (NSUserDefaults / SharedPreferences) or the network.

• Denylist: remove matching keys.
• Classify: a per-key action. The first rule for a key wins.
  • DROP: remove the key.
  • REDACT: replace the value with "<redacted>".
  • TOKENIZE: replace it with t:1, t:2, …, stable for the tracker's lifetime.
  • HASH: h: plus FNV-1a 32-bit hex. It's identical to the web tracker, so the same value hashes the same on both platforms. Not cryptographic.

Keys match exactly (case-sensitive) at any depth, including inside lists.

// Android
val score = newScoreTracker(
    context, config,
    pii = PiiOptions.Classify(listOf(
        PiiRule("email", PiiAction.HASH),         // joinable across web + app
        PiiRule("phone", PiiAction.REDACT),
        PiiRule("memberNumber", PiiAction.TOKENIZE),
        PiiRule("dateOfBirth", PiiAction.DROP),
    )),
)
score.track("profile_updated", mapOf("email" to "fan@example.com", "favouriteTeam" to "home-club"))
// queued and sent as {"email":"h:141e28bb","favouriteTeam":"home-club"}

// iOS
let score = ScoreClient(
    publishableKey: "pk_…", siteId: "app.example.com-1a2b3c",
    endpoint: "https://api.example.com",
    pii: PiiOptions.Classify(rules: [
        PiiRule(field: "email", action: .hash_),     // `hash_`, not `hash`: that name is NSObject's
        PiiRule(field: "phone", action: .redact),
        PiiRule(field: "memberNumber", action: .tokenize),
        PiiRule(field: "dateOfBirth", action: .drop),
    ])
)

To remove keys without per-field actions, use PiiOptions.Denylist(listOf("email", "phone")).

Auth0 (JWT)

Mirrors the web tracker's getToken (#109, #483): supply a token provider. It's consulted before each flush, so flushes carry a fresh access token. It is async, so hand it Auth0's own refresh call directly; there's nothing to block on or cache yourself.

// iOS — Auth0.swift's CredentialsManager renews the token when it's expired.
score.setTokenProvider { try await credentialsManager.credentials().accessToken }
score.identify(userId: "auth0|abc123")   // optional: set userId now

// Android — Auth0.Android's CredentialsManager has a suspend awaitCredentials().
score.setTokenProvider { credentialsManager.awaitCredentials().accessToken }
score.identify("auth0|abc123")

Signing in: traits and replay (#488)

identify takes the fan's traits, sent on an identify event (consent-gated and PII-scrubbed like any props). Pass replayAnonymousEvents to re-send the events the app already sent while the fan was signed out, now with the fan attached, so a poll vote cast before sign-in still earns its karma:

score.identify(userId: "auth0|abc123", traits: ["team": "urc-leinster"], replayAnonymousEvents: true)

score.identify("auth0|abc123", traits = mapOf("team" to "urc-leinster"), replayAnonymousEvents = true)

Replay is opt-in. It re-sends at most the last 100 anonymously sent events (identifyReplayBufferSize on the factory / ScoreClient init), only those current consent still allows, marked _backfill: true with _originalEventId. Events still waiting in the queue aren't replayed: they go out with the fan on the next flush. The buffer lives in memory only, so it's empty after a cold start.

How the provider is used:

• Before each flush, and single-flight: overlapping flushes share one in-flight call instead of starting several.
• Bounded: if it hasn't answered within 5 s, the flush goes ahead without waiting. The call keeps running, and its token is used once it arrives. Android can change this with the tokenRefreshTimeoutMs parameter on ScoreTracker.
• Never halts tracking: if the provider throws or returns null, the flush uses the last known token, or goes anonymous if there isn't one.
• A synchronous closure still works ({ cachedToken }), so existing code compiles unchanged.

Offline & flushing

• Durable queue: events persist (NSUserDefaults / SharedPreferences), survive cold start, are FIFO-capped (oldest dropped), and clear only on a successful POST (a failed flush retains them for retry).

• Lifecycle & connectivity — one call (#484). Bind the tracker once at startup and it flushes when it should:

  // iOS — in application(_:didFinishLaunchingWithOptions:)
  score.bindToAppLifecycle()
  

  // Android — in Application.onCreate(), on the main thread
  score.bindToAppLifecycle(this)
  

  When	What the tracker does
  App comes to the foreground (or is already there when you bind)	Flush, and flush every 30 s while it stays there
  App goes to the background	Stop the periodic flush; one best-effort flush bounded to 5 s, so it can't hold up suspension (on iOS, inside a background task that ends as soon as the flush does)
  Network comes back	Flush

  Both platforms run the same shared logic. Options: autoFlushEverySeconds / autoFlushIntervalMs (nil/null to run your own auto-flush) and backgroundBudgetSeconds / backgroundBudgetMs. Undo with unbindAppLifecycle() (iOS) or close() on the returned binding (Android). Android declares ACCESS_NETWORK_STATE in the library manifest, a normal permission with no prompt. A bounded flush that runs out of time loses nothing: events leave the queue only after their POST succeeds.

• Delivery tiers (#487). Mark an event that must not be lost as critical:

  score.track(Events.shared.PollVote, props: […], delivery: .critical)        // iOS
  

  score.track(Events.PollVote, mapOf(…), delivery = DeliveryMode.CRITICAL)    // Android
  

  Critical events go out first in every flush, survive app restarts as critical, and are the last to go when the queue is full: best-effort events, including new ones, are shed before any critical event. If a critical event is lost anyway, because it aged past 72 h or the queue was entirely critical, the SDK sends a delivery_failed event naming it (originalEventId, originalEventName, reason: age_evicted or queue_full), the same event the web tracker sends. The tier is local: it never appears on the wire.

• Manual control instead: binding is opt-in. Skip it and call onForeground(), onBackground() and onNetworkAvailable() yourself, plus startAutoFlush(everySeconds: 30) (iOS) / startAutoFlush(scope, intervalMs) (Android).

Canonical app earning events

type: "track" with these names (props open; matched by the Odoo rules engine):

name	example props
poll_vote	{ pollId, choice }
motm_submit	{ matchId, playerId }
player_rating	{ matchId, playerId, rating }
minigame_play	{ game, result, score }
streak_tick	{ streakType, currentDays }

See conformance/fixtures/ for full golden envelopes.