3HL-SCORE/public-sdks-score
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Publish Score iOS SDK 0.3.0

Browse Source
This commit is contained in:
bdot
2026-10-04 22:44:35 -04:00
parent 411afa70a2
commit 47531c5192
7 changed files with 330 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
INTEGRATION.md
View File

@@ -8,9 +8,9 @@ identically — see [`conformance/CONTRACT.md`](conformance/CONTRACT.md).
---
## Install — 0.2.0 beta (public, no auth)
## Install — 0.3.0 beta (public, no auth)
Distributed publicly from **[`3HL-SCORE/public-sdks-score`](https://git.3halves-labs.com/3HL-SCORE/public-sdks-score)** (#284) — **no Gitea token / login required**. The iOS XCFramework is a public **release asset** (`mobile-v0.2.0`) on that repo; the Android artifacts live in the org's **Gitea Maven package registry** (anonymous read).
Distributed publicly from **[`3HL-SCORE/public-sdks-score`](https://git.3halves-labs.com/3HL-SCORE/public-sdks-score)** (#284) — **no Gitea token / login required**. The iOS XCFramework is a public **release asset** (`mobile-v0.3.0`) on that repo; the Android artifacts live in the org's **Gitea Maven package registry** (anonymous read).
### Android — Gradle (public Maven registry)
```kotlin
@@ -18,7 +18,7 @@ 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.2.0")
implementation("com.threehalveslabs.scoretracker:shared-android:0.3.0")
}
```
@@ -34,19 +34,21 @@ add it by **git URL** — no registry config, no login:
```swift
// your app's Package.swift
dependencies: [
.package(url: "https://git.3halves-labs.com/3HL-SCORE/public-sdks-score.git", from: "0.2.0")
.package(url: "https://git.3halves-labs.com/3HL-SCORE/public-sdks-score.git", from: "0.3.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.2.0` release asset (SPM
target pulls the XCFramework from the **public** `mobile-v0.3.0` release asset (SPM
verifies the checksum) — no `~/.netrc` credentials needed. Verified with an
anonymous `swift package resolve`.
### iOS — direct XCFramework
Download `ScoreTrackerKit.xcframework.zip` from the **mobile-v0.2.0** release on
[`public-sdks-score`](https://git.3halves-labs.com/3HL-SCORE/public-sdks-score/releases)
and drag the `.xcframework` into your Xcode project; add `ScoreClient.swift`.
Download `ScoreTracker-pod.zip` from the **mobile-v0.3.0** release on
[`public-sdks-score`](https://git.3halves-labs.com/3HL-SCORE/public-sdks-score/releases).
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.
---
@@ -59,7 +61,6 @@ let score = ScoreClient(
publishableKey: "pk_live_…",
siteId: "urc-ios",
endpoint: "https://<middleware-host>",
sdkVersion: "0.2.0",
appVersion: Bundle.main.shortVersion,
os: "iOS \(UIDevice.current.systemVersion)",
device: UIDevice.current.model,
@@ -69,14 +70,26 @@ let score = ScoreClient(
// 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"])
// 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.
@@ -94,7 +107,6 @@ val score = newScoreTracker(
publishableKey = "pk_live_…",
siteId = "urc-android",
endpoint = "https://<middleware-host>",
sdk = SdkInfo("@3halves-labs/score-tracker-android", "0.2.0"),
device = DeviceDescriptor(os = "Android ${Build.VERSION.RELEASE}", device = Build.MODEL,
appVersion = BuildConfig.VERSION_NAME, locale = Locale.getDefault().toLanguageTag()),
),
@@ -136,9 +148,12 @@ score.setConsent(analytics: groups.analytics, personalization: groups.personaliz
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.
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
@@ -174,9 +189,9 @@ score.track("profile_updated", mapOf("email" to "fan@example.com", "favouriteTea
// iOS
let score = ScoreClient(
publishableKey: "pk_…", siteId: "app.example.com-1a2b3c",
endpoint: "https://api.example.com", sdkVersion: "0.2.0",
endpoint: "https://api.example.com",
pii: PiiOptions.Classify(rules: [
PiiRule(field: "email", action: .hash),
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),
@@ -189,29 +204,85 @@ To remove keys without per-field actions, use
## 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.
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.
```swift
score.setTokenProvider { Auth0Session.shared.accessToken } // called before each flush
score.identify(userId: "auth0|abc123") // optional: set userId now
// 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
```
```kotlin
score.setTokenProvider { auth0.credentials?.accessToken }
// Android — Auth0.Android's CredentialsManager has a suspend awaitCredentials().
score.setTokenProvider { credentialsManager.awaitCredentials().accessToken }
score.identify("auth0|abc123")
```
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).
- **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).
- **Lifecycle & connectivity — one call (#484).** Bind the tracker once at
startup and it flushes when it should:
```swift
// iOS — in application(_:didFinishLaunchingWithOptions:)
score.bindToAppLifecycle()
```
```kotlin
// 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:
```swift
score.track(Events.shared.PollVote, props: […], delivery: .critical) // iOS
```
```kotlin
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