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.1.0 beta (hosted on Gitea)

Everything is hosted on the org's Gitea — no external registry. The Android artifacts live in Gitea's Maven package registry; the iOS XCFramework is a Gitea release asset (mobile-v0.1.0).

Android — Gradle (Gitea Maven registry)

repositories {
    maven {
        url = uri("https://git.3halves-labs.com/api/packages/3HL-SCORE/maven")
        // If the package registry isn't public, add a Gitea token:
        // credentials(HttpHeaderCredentials::class) { name = "Authorization"; value = "token ${'$'}giteaToken" }
        // authentication { create<HttpHeaderAuthentication>("header") }
    }
}
dependencies {
    implementation("com.threehalveslabs.scoretracker:shared-android:0.1.0")
}

iOS — CocoaPods (release asset)

pod 'ScoreTracker',
    :podspec => 'https://git.3halves-labs.com/3HL-SCORE/score-anything-loyalty/raw/branch/main/mobile/ios/ScoreTracker/ScoreTracker.podspec'

iOS — Swift Package Manager (Gitea Swift registry)

Published to Gitea's Swift package registry as threehalveslabs.ScoreTracker. Configure the registry once (per machine / CI), then add it as a normal dependency by id — no git URL needed:

swift package-registry set https://git.3halves-labs.com/api/packages/3HL-SCORE/swift
# private registry → log in with a Gitea token:
swift package-registry login https://git.3halves-labs.com/api/packages/3HL-SCORE/swift --token <gitea-token>

// your app's Package.swift
dependencies: [ .package(id: "threehalveslabs.ScoreTracker", from: "0.1.0") ]
// then: .product(name: "ScoreTracker", package: "ScoreTracker")

The package's binary ScoreTrackerKit target pulls the XCFramework from the mobile-v0.1.0 release asset (SPM verifies the checksum). For a private release asset, SPM reads credentials from ~/.netrc.

Note: SPM-by-git-URL isn't available (the package lives in a monorepo subdir, which SPM can't resolve) — the Swift registry above is the supported path.

iOS — direct XCFramework

Download ScoreTrackerKit.xcframework.zip from the mobile-v0.1.0 release and drag the .xcframework into your Xcode project; add ScoreClient.swift.

---

iOS (Swift)

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

let score = ScoreClient(
    publishableKey: "pk_live_…",
    siteId: "urc-ios",
    endpoint: "https://<middleware-host>",
    sdkVersion: "0.1.0",
    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
score.track("poll_vote", props: ["pollId": "motm-r12", "choice": "player_7"])
score.screen("match_centre")

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

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>",
        sdk = SdkInfo("@3halves-labs/score-tracker-android", "0.1.0"),
        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 (e.g. trackAdvertising(...) on iOS, or requires = listOf(ConsentCategory.ADVERTISING) on Android) are dropped until that category is granted.

Auth0 (JWT)

Mirrors the web tracker (#109): supply a token provider — it's consulted before each flush, so flushes carry a fresh access token. Failure → anonymous, never halts.

score.setTokenProvider { Auth0Session.shared.accessToken } // called before each flush
score.identify(userId: "auth0|abc123")                     // optional: set userId now

score.setTokenProvider { auth0.credentials?.accessToken }
score.identify("auth0|abc123")

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).
• Auto-flush: score.startAutoFlush(everySeconds: 30) (iOS) / score.startAutoFlush(scope, intervalMs) (Android).
• Lifecycle hooks: call onForeground() / onNetworkAvailable() to flush promptly — wire them to UIApplication/NWPathMonitor (iOS) or ProcessLifecycleOwner/connectivity callbacks (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.