Documentation Index
Fetch the complete documentation index at: https://285e39fd5e337e58f16290.sightscreen.app/llms.txt
Use this file to discover all available pages before exploring further.
Three token types
The push system uses three distinct token types. Understanding which is which will save you debugging time at 2am.| Token | Stored in | Registered via | Purpose |
|---|---|---|---|
| pushToken | devices table | POST /devices | Standard push notifications. Used for prematch alerts, marketing, etc. One per device. |
| pushToStartToken | devices table | POST /devices/push-to-start-token | Allows backend to remotely create a Live Activity on the device. One per device. Registered once on app launch. |
| updateToken | live-activities table | POST /matches/:matchId/activity-token | Update or end a specific Live Activity instance. One per LA. Tied to the LA lifecycle. |
Multi-device support
A user can be signed in on multiple iOS devices simultaneously. Each device registers independently. Thedevices table uses deviceId (identifierForVendor) as the sort key — not the push token. This means:
- Each device gets its own record under the same userId
- Token rotation (OS updates, reinstalls) updates the existing record in-place
- No single-device enforcement — all devices receive pushes
identifierForVendor resets on app reinstall. When a user reinstalls, the old device record becomes orphaned. The 90-day TTL on lastSeenAt handles eventual cleanup, but there’s a window where both old and new records exist.Devices table schema
| Attribute | Type | Description |
|---|---|---|
userId (PK) | String | Cognito user ID |
deviceId (SK) | String | identifierForVendor from iOS |
pushToken | String | APNs device push token |
pushToStartToken | String | ActivityKit push-to-start token |
osVersion | String | e.g., 18.2 |
appVersion | String | e.g., 2.1.0 |
lastSeenAt | Number | Epoch timestamp, updated on each registration |
ttl | Number | 90 days from lastSeenAt (DynamoDB auto-delete) |
Registration flow on app launch
Every app launch triggers a registration call. This keeps tokens fresh and metadata current.Request permissions
On first launch, iOS shows the notification permission prompt. On subsequent launches, the app checks existing permission status.
Get device pushToken
If permissions are granted, iOS registers with APNs and returns the device push token. This token can change after OS updates.
POST /devices
The app sends
pushToken, deviceId, osVersion, and appVersion. The backend upserts the device record and refreshes lastSeenAt and ttl.Unregistration on sign-out
When the user signs out:- iOS calls
DELETE /devices/:deviceId - Backend removes the device record from the
devicestable - Any active
live-activitiesrecords for this device are NOT automatically cleaned up (they’ll expire via TTL or get caught by the Orchestrator’s recovery loop) - iOS clears all local state
Failure modes
| Scenario | Behavior |
|---|---|
| User denies notification permissions | No tokens generated; app works but no push of any kind |
| Token changes after OS update | App re-registers on next launch; record updated in-place |
| App reinstalled | New deviceId generated; old record orphaned until TTL expires |
| Registration POST fails | Logged but not retried until next app launch |
| pushToStartToken POST fails | LA cannot be started remotely; user must open app to create LA manually |
Key endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /devices | Register device + pushToken |
| POST | /devices/push-to-start-token | Register push-to-start token |
| POST | /matches/:matchId/activity-token | Register per-activity update token |
| DELETE | /devices/:deviceId | Unregister device on sign-out |
Related pages
- Live Activity lifecycle — how push-to-start tokens are used to create LAs
- Match following — the flow that triggers update token registration
- Authentication flow — sign-in triggers device registration