docs(push): add iOS Live Activities page by ttypic · Pull Request #3464 · ably/docs

ttypic · 2026-07-08T12:55:22Z

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

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-07-08T12:55:31Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 779977c7-008b-43f2-b18c-84dacd8cb179

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch liveactivity-section

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

lawrence-forooghian · 2026-07-08T17:25:42Z

+
+* 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.


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.

lawrence-forooghian · 2026-07-08T17:27:11Z

+
+## 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.


That page seems to default to Java, which doesn't have #apns; I think /docs/push/configure/device?lang=swift#apns

Actually I need to verify this in the review app; I just navigated directly to the page

Yeah, just tried it in the review app; this link doesn't work

lawrence-forooghian · 2026-07-08T17:29:48Z

+
+<Code>
+```swift
+rest.push.activate(pushToStart: token)


Where can I find this API? It's not in ably/ably-cocoa#2219

Yeah, I wanted to propose this API as alternative, but deleted, it requires spec changes

lawrence-forooghian · 2026-07-08T17:31:50Z

+
+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.


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.

Sorry I think I didn't have the right mental model here, will come back to 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

lawrence-forooghian · 2026-07-08T17:39:56Z

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.

lawrence-forooghian · 2026-07-08T17:56:27Z

+```
+</Code>
+
+Finally, make the device targetable for push-to-start. Either subscribe it to an Ably channel:


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"

JoaoDiasAbly · 2026-07-09T11:04:45Z

+
+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.


three API calls

Feels a bit misleading since it's actually a one-time create plus the three lifecycle calls

JoaoDiasAbly · 2026-07-09T11:06:31Z

+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.


Think the style guide prohibits bold list prefixes as well as em-dashes

JoaoDiasAbly · 2026-07-09T11:06:49Z

+* 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.


style guide (em-dashes)

JoaoDiasAbly · 2026-07-09T11:06:58Z

+```
+</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:


style guide (em-dashes)

JoaoDiasAbly · 2026-07-09T11:09:36Z

+
+## 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.


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

JoaoDiasAbly · 2026-07-09T11:10:53Z

+* `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"/>


Should we also add a point saying the key/token needs the push-admin capability?

JoaoDiasAbly · 2026-07-09T11:12:06Z

+
+* 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.


Aren't broadcast channels only available from iOS 18+? And 17.2 is push-to-start only?

JoaoDiasAbly · 2026-07-09T11:25:14Z

+```
+</Code>
+
+The underlying REST endpoint is `POST /push/apnsBroadcastChannels/{id}/broadcast`.


Maybe add one clause on why update() posts to /broadcast — an update is a single broadcast to the channel

JoaoDiasAbly · 2026-07-09T11:26:41Z

+| `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. |


Is this also used in update (not just start)?

- Attribute update fan-out to APNs and clarify the one-time channel create plus three lifecycle calls in the intro - Fix the APNs config link (needs ?lang=swift) and use ".p8 authentication key" terminology - Add the push-admin capability prerequisite - Correct iOS requirements: broadcast channels need iOS 18, not 17.2 - Remove the activate(pushToStart:) section; that API is not yet in ably-cocoa - Clarify that the Ably channel only selects push-to-start targets and is unrelated to the APNs broadcast channel - Note that update() posts to /broadcast because an update is a single broadcast, and that alert is also valid in update events - Style guide fixes: remove em-dashes and bold list prefixes Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ttypic requested a review from m-hulbert July 8, 2026 12:55

ttypic requested a review from JoaoDiasAbly July 8, 2026 13:30

ttypic mentioned this pull request Jul 8, 2026

Add API for registering Live Activity push-to-start token ably/ably-cocoa#2219

Merged

lawrence-forooghian added the review-app Create a Heroku review app label Jul 8, 2026

ably-ci temporarily deployed to ably-docs-liveactivity--kmqavy July 8, 2026 17:19 Inactive

lawrence-forooghian reviewed Jul 8, 2026

View reviewed changes

JoaoDiasAbly reviewed Jul 9, 2026

View reviewed changes

ably-ci temporarily deployed to ably-docs-liveactivity--kmqavy July 10, 2026 09:04 Inactive

ttypic force-pushed the liveactivity-section branch from 3561365 to 009ead0 Compare July 10, 2026 10:10

ably-ci temporarily deployed to ably-docs-liveactivity--kmqavy July 10, 2026 10:10 Inactive

ttypic force-pushed the liveactivity-section branch from 009ead0 to a59c5b0 Compare July 10, 2026 12:45

ably-ci deployed to ably-docs-liveactivity--kmqavy July 10, 2026 12:45 View deployment

ttypic requested review from JoaoDiasAbly and lawrence-forooghian July 10, 2026 12:47


		## 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.


		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.

Uh oh!

Conversation

ttypic commented Jul 8, 2026

Description

Checklist

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lawrence-forooghian commented Jul 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading