docs(push): add iOS Live Activities page#3464
Conversation
Document starting, updating, and ending iOS Live Activities via Ably-managed APNs broadcast channels: device registration with push-to-start tokens, broadcast channel creation, the start/update/end server calls, and an aps payload and headers reference. Marked Experimental.
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
||
| * An Ably app with [APNs configured](/docs/push/configure/device#apns): upload your APNs signing key so Ably can push on your behalf. | ||
| * An iOS app with the `NSSupportsLiveActivities` Info.plist key, a Live Activity widget extension, and an `ActivityAttributes` model. | ||
| * iOS 16.1 or later for Live Activities; iOS 17.2 or later for push-to-start and broadcast channels. |
There was a problem hiding this comment.
iOS 16.1 or later for Live Activities
What functionality does Ably give you if you're on iOS < 17.2? It seems like all our functionality is built around broadcast channels.
|
|
||
| ## Prerequisites <a id="prerequisites"/> | ||
|
|
||
| * An Ably app with [APNs configured](/docs/push/configure/device#apns): upload your APNs signing key so Ably can push on your behalf. |
There was a problem hiding this comment.
That page seems to default to Java, which doesn't have #apns; I think /docs/push/configure/device?lang=swift#apns
There was a problem hiding this comment.
Actually I need to verify this in the review app; I just navigated directly to the page
There was a problem hiding this comment.
Yeah, just tried it in the review app; this link doesn't work
|
|
||
| <Code> | ||
| ```swift | ||
| rest.push.activate(pushToStart: token) |
There was a problem hiding this comment.
Where can I find this API? It's not in ably/ably-cocoa#2219
|
|
||
| Live Activities display an app's live state on the iOS lock screen and in the Dynamic Island, for example a sports scoreboard, a delivery tracker, or the progress of a long-running task. Apple updates Live Activities through APNs rather than through the app itself, which normally means collecting and refreshing a push token for every activity on every device. | ||
|
|
||
| Ably removes that bookkeeping. Ably holds your APNs credentials, manages [APNs broadcast channels](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications) on your behalf, and fans a single publish out to every activity subscribed to the broadcast channel. Your server starts, updates, and ends Live Activities with three API calls, and devices register themselves using the same [push activation](/docs/push/configure/device) flow used for ordinary push notifications. |
There was a problem hiding this comment.
and fans a single publish out to every activity subscribed to the broadcast channel
Isn't it APNs that "fans out"? That's what we say further down:
APNs fans it out to every subscribed activity on every device — no per-activity tokens involved.
There was a problem hiding this comment.
Sorry I think I didn't have the right mental model here, will come back to this comment
There was a problem hiding this comment.
So as I understand it, what Ably fans out is the creation of the activity (to each matching device), not the updates (which is handled by APNs) — "and fans a single publish out to every activity subscribed to the broadcast channel" suggests we handle the latter
|
Probably a question for the devex team but is there a way to force it to show something for a snippet even if it's not in the selected language? Else you have to keep flipping the language selector between JS and Swift to view the full page. |
| ``` | ||
| </Code> | ||
|
|
||
| Finally, make the device targetable for push-to-start. Either subscribe it to an Ably channel: |
There was a problem hiding this comment.
It took me a while to understand why Ably channels are introduced here. I think it would be useful to say something like "the Ably channel is only used to select which devices to push-to-start; it has nothing to do with the broadcast channel that carries updates"
|
|
||
| Live Activities display an app's live state on the iOS lock screen and in the Dynamic Island, for example a sports scoreboard, a delivery tracker, or the progress of a long-running task. Apple updates Live Activities through APNs rather than through the app itself, which normally means collecting and refreshing a push token for every activity on every device. | ||
|
|
||
| Ably removes that bookkeeping. Ably holds your APNs credentials, manages [APNs broadcast channels](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications) on your behalf, and fans a single publish out to every activity subscribed to the broadcast channel. Your server starts, updates, and ends Live Activities with three API calls, and devices register themselves using the same [push activation](/docs/push/configure/device) flow used for ordinary push notifications. |
There was a problem hiding this comment.
three API calls
Feels a bit misleading since it's actually a one-time create plus the three lifecycle calls
| 1. **Create a broadcast channel.** Your server asks Ably to create an APNs broadcast channel. Ably returns a pair of identifiers: an opaque broadcast `id`, which your server uses in every subsequent start, update, and end call, and an `apnsChannelId`, which iOS devices use to subscribe an activity to the channel. | ||
|
|
||
| 2. **Start the Live Activity.** Either: | ||
| * **Push-to-start from the server.** Devices that have registered a Live Activity push-to-start token with Ably can have activities started remotely. The start payload includes the `apnsChannelId` (as `input-push-channel`), so the started activity is subscribed to the broadcast channel immediately. | ||
| * **Locally in the app.** The app starts the activity itself with `pushType: .channel(apnsChannelId)`, subscribing it to the broadcast channel. | ||
|
|
||
| 3. **Update and end by broadcast.** Each state change is a single publish against the broadcast `id`. APNs fans it out to every subscribed activity on every device — no per-activity tokens involved. Creating the channel with `messageStoragePolicy: 1` caches the most recent update so late-joining activities receive the current state as soon as they subscribe. |
There was a problem hiding this comment.
Think the style guide prohibits bold list prefixes as well as em-dashes
| * An Ably app with [APNs configured](/docs/push/configure/device#apns): upload your APNs signing key so Ably can push on your behalf. | ||
| * An iOS app with the `NSSupportsLiveActivities` Info.plist key, a Live Activity widget extension, and an `ActivityAttributes` model. | ||
| * iOS 16.1 or later for Live Activities; iOS 17.2 or later for push-to-start and broadcast channels. | ||
| * Clients should authenticate with [token authentication](/docs/auth/token) — for example an `authUrl` pointing at your server — so the API key never ships in the app. |
There was a problem hiding this comment.
style guide (em-dashes)
| ``` | ||
| </Code> | ||
|
|
||
| If the device only needs Live Activity push-to-start — and never ordinary push notifications — activate with the push-to-start token alone. This registers the device without requesting an APNs device token: |
There was a problem hiding this comment.
style guide (em-dashes)
|
|
||
| ## Prerequisites <a id="prerequisites"/> | ||
|
|
||
| * An Ably app with [APNs configured](/docs/push/configure/device#apns): upload your APNs signing key so Ably can push on your behalf. |
There was a problem hiding this comment.
Should we use ".p8 authentication key" rather than "signing key"? Check with Claude and it seems to be the term the linked page and all other push docs use
| * `Date` properties in attributes or content state travel as Unix epoch **seconds**, which is how ActivityKit decodes JSON dates by default. | ||
| </Aside> | ||
|
|
||
| ## Prerequisites <a id="prerequisites"/> |
There was a problem hiding this comment.
Should we also add a point saying the key/token needs the push-admin capability?
|
|
||
| * An Ably app with [APNs configured](/docs/push/configure/device#apns): upload your APNs signing key so Ably can push on your behalf. | ||
| * An iOS app with the `NSSupportsLiveActivities` Info.plist key, a Live Activity widget extension, and an `ActivityAttributes` model. | ||
| * iOS 16.1 or later for Live Activities; iOS 17.2 or later for push-to-start and broadcast channels. |
There was a problem hiding this comment.
Aren't broadcast channels only available from iOS 18+? And 17.2 is push-to-start only?
| ``` | ||
| </Code> | ||
|
|
||
| The underlying REST endpoint is `POST /push/apnsBroadcastChannels/{id}/broadcast`. |
There was a problem hiding this comment.
Maybe add one clause on why update() posts to /broadcast — an update is a single broadcast to the channel
| | `attributes-type` | start | The exact name of the Swift `ActivityAttributes` struct. | | ||
| | `attributes` | start | The activity's fixed attributes; `Date` values as Unix epoch seconds. | | ||
| | `input-push-channel` | start | The `apnsChannelId` the started activity subscribes to for broadcast updates. | | ||
| | `alert` | start | The user-visible notification shown when the activity starts. | |
There was a problem hiding this comment.
Is this also used in update (not just start)?
4 participants
Description
Document starting, updating, and ending iOS Live Activities via Ably-managed APNs broadcast channels: device registration with push-to-start tokens, broadcast channel creation, the start/update/end server calls, and an aps payload and headers reference. Marked Experimental.
Checklist