Publish Score iOS SDK 0.5.0

INTEGRATION.md

@@ -8,9 +8,9 @@ identically — see [`conformance/CONTRACT.md`](conformance/CONTRACT.md).
 
 ---
 
-## Install — 0.4.0 beta (public, no auth)
+## Install — 0.5.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.4.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.5.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.4.0")
+    implementation("com.threehalveslabs.scoretracker:shared-android:0.5.0")
 }
 ```
 
@@ -34,17 +34,17 @@ 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.4.0")
+    .package(url: "https://git.3halves-labs.com/3HL-SCORE/public-sdks-score.git", from: "0.5.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
+target pulls the XCFramework from the **public** `mobile-v0.5.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
+Download `ScoreTracker-pod.zip` from the **mobile-v0.5.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`).
@@ -241,6 +241,15 @@ 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.
 
+After `identify`, the tracker also links this device's `anonymousId` to the fan
+(`POST /api/identity/link-anonymous`, with the token from your provider or
+`setToken`), so the server can credit events that arrive with only the
+`anonymousId`. It happens once per fan per device, on the next flush, after the
+events; it needs `analytics` consent and a token, and a failure never affects
+event delivery. Android's `score.lastLinkSkipReason()` (`already_linked`,
+`consent`, `no_token`, `error`) says why a link hasn't happened. A custom
+`Transport` must implement `postWithHeaders` for this call to carry the token.
+
 How the provider is used:
 - **Before each flush**, and **single-flight**: overlapping flushes share one
   in-flight call instead of starting several.
@@ -305,6 +314,28 @@ How the provider is used:
   `startAutoFlush(everySeconds: 30)` (iOS) / `startAutoFlush(scope, intervalMs)`
   (Android).
 
+## Bug reports: attach `inspectJson()`
+
+When the tracker misbehaves in the field, the first thing to attach is its
+snapshot (#490), the counterpart of the web tracker's `inspect()`:
+
+```swift
+print(score.inspectJson())          // iOS
+```
+```kotlin
+Log.d("Score", score.inspectJson()) // Android
+```
+
+It covers:
+- the SDK name and version
+- consent: each category, and how many events the gate dropped
+- the queue: depth, caps, the oldest event's age, critical events, critical events lost
+- identity: `anonymousId`, `sessionId`, `userId`, whether a token is held, the `link-anonymous` state and the replay buffer
+- the last flush: when, whether it succeeded, how many events it sent, and how many failures in a row
+- site, endpoint and the number of PII rules
+
+**It never contains the token**, only `hasToken`, so it's safe to log or paste. `inspect()` returns the same data as a typed `InspectSnapshot`.
+
 ## Canonical app earning events
 
 `type: "track"` with these names (props open; matched by the Odoo rules engine):