Add push notifications guide #2983

vladvelici · 2025-11-27T10:35:05Z

Description

https://ably.atlassian.net/browse/FF-146

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 · 2025-11-27T10:35:11Z

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.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch push-notifications-guide

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 and usage tips.}

src/pages/docs/guides/pubsub/push-notifications.mdx

david-hernandez-ably · 2025-12-03T14:29:37Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+```kotlin
+// Android
+val ably = getAblyRealtime()
+ably.setAndroidContext(context)


Is it complex to show here what context is?

david-hernandez-ably · 2025-12-03T14:35:37Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+<Code>
+```javascript
+// Update device registration
+await client.push.admin.deviceRegistrations.save({


Is there an API to delete registrations as well?

david-hernandez-ably · 2025-12-03T14:37:34Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+  }
+}));
+
+// Send up to 10,000 notifications in one request


Do we charge per REST request or per notification?

david-hernandez-ably · 2025-12-03T14:39:00Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+
+Push notification failures are inevitable: devices go offline, users uninstall apps, tokens expire. Monitoring and handling errors properly is critical.
+
+Ably publishes push errors to a dedicated meta channel `[meta]log:push`. Monitor this channel to track push notification delivery errors.


Is this a channel reserved name? Does this channel exist for all the accounts?

Do we bill for the messages sent to this meta channel?

Yes to all three questions.

AndyTWF

Thanks for this, a few general thoughts:

Where we have codeblocks, we should have them in all the languages that are relevant. We should also include other Pub/Sub languages (e.g. Go, Ruby) if the SDKs support it.
Can we link the architecture docs somewhere to hammer home the scale aspect? We should also continue to make reference to our four pillars, SLA and uptime to make it clear why Ably is the right choice at scale.
We should discuss tradeoffs in various decisions in terms of pricing, where that's applicable.
Can we add a mockup of a PN (happy for this to be designed) to illustrate?
From about half way through, things start to turn into an extended docs page - can we try to refocus them more on where Ably differentiates and excels at scale?

src/pages/docs/guides/pubsub/push-notifications.mdx

AndyTWF · 2025-12-04T10:10:19Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+```javascript
+// Subscribe to all channels, and push-subscribe for "news:" channels; suitable for a client:
+{
+  '*': ['subscribe'],                        // Can subscribe to realtime messages


This is lacking context - where do these things get passed in? We should probably call out where this would be set up.

Possibly worth making this a JSON block and not a code block, otherwise we need to add additional languages.

AndyTWF · 2025-12-04T10:13:19Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+Follow these practices:
+
+* Never give clients `push-admin` capability. They could manage registrations and subscriptions for push notifications for any device.
+* Do not give `publish` capability to clients on channels used for push notifications. This could allow any clients to publish push notifications to that channel.


Is this a hard no, or just a recommendation? Is there a case where someone might want this?

My take is that I can't see a use case to be honest, it's all risky to allow it. So hard no, unless you know what you're doing, in which case you'll ignore this sentence anyway (and it includes why not so I'd leave it in). More trouble than worth?

I have to make it stronger

Suggested change

* Do not give `publish` capability to clients on channels used for push notifications. This could allow any clients to publish push notifications to that channel.

* Do not give `publish` capability to clients on channels used for push notifications. This will allow any clients to publish push notifications to that channel.

AndyTWF · 2025-12-04T10:15:07Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+When users disable notifications in your app or log out, remove the device registration from Ably:
+
+<Code>
+```javascript


Other languages?

AndyTWF · 2025-12-04T10:15:35Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+* Any other business logic.
+
+<Code>
+```javascript


I wouldn't put this as a code block - as otherwise we have to duplicate across each (and it isn't code).

…language, or is not even code

AndyTWF · 2025-12-08T12:19:54Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+});
+```
+
+```java


As this is server-side, lets also add:

Ruby

Go

PHP

Here and the publish example, it makes sense.

Go doesn't seem to have push admin yet so it'll look like rest.Request() but that should be fine. Maybe a curl example will be good too to show the API. Ruby seems to have it. Will check PHP. Probably python too, it looks like we might have push admin for it.

AndyTWF · 2025-12-08T12:28:24Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+
+Ably publishes delivery feedback to the `[meta]log:push` channel in real-time. This gives you immediate visibility into failures - invalid tokens, expired registrations, platform outages - so you can maintain a clean device registry and debug issues quickly. Ably also handles automatic retries when APNs or FCM experience transient issues, so you don't need to build retry logic yourself.
+
+## Production-ready checklist


Before the production ready checklist - I think we should try to come back to one final "why Ably" callout, even if it's just a few sentences. It gives us a chance to call out the key USPs, scale etc - one final emphasis on where Ably wins.

AndyTWF · 2025-12-08T12:29:36Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+}
+```
+
+This lets you use platform-specific features while maintaining a single codebase for notification publishing.


Worth calling out explicitly that without Ably, you'd have to maintain 3 different platform-specific transformation layers

AndyTWF · 2025-12-08T12:46:45Z

src/pages/docs/guides/pubsub/push-notifications.mdx

+
+## Device activation at scale
+
+Before [devices](/docs/push/configure/device) or [browsers](/docs/push/configure/web) can receive push notifications, they must be activated - registered with both the platform's push service (APNs, FCM, or Web Push) and with Ably. Ably handles the complexity of maintaining these registrations at scale, including token refresh, mapping devices to users, and keeping track of subscriptions to channels.


Another key one to call out here is that we automatically handle stale registrations and exclude them from fanout, so you don't have to worry about stale devices causing delivery failures (e.g. due to inactivity, reinstalling app etc).

We can say something along the lines of (don't quote me, just an example) "at scale, stale registrations accumulate quickly, with Ably, this is entirely handled for you, with metachannels for monitoring key events in real time"

We also handle automatically refreshing server credentials to talk to FCM/APNs etc

vladvelici requested review from a team and AndyTWF November 27, 2025 10:35

vladvelici force-pushed the push-notifications-guide branch from 1b7f8ce to d429c0b Compare November 27, 2025 10:41

Add push notifications guide

828e537

vladvelici force-pushed the push-notifications-guide branch from d429c0b to 828e537 Compare November 27, 2025 10:45

mention retires if delivery platforms are down

882a0aa

AndyTWF added the review-app Create a Heroku review app label Dec 3, 2025

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 3, 2025 10:06 Inactive

david-hernandez-ably approved these changes Dec 3, 2025

View reviewed changes

AndyTWF reviewed Dec 4, 2025

View reviewed changes

vladvelici added 3 commits December 5, 2025 02:19

review fixes: remove code blocks when code is not really linked to a …

f82e1f7

…language, or is not even code

merge activation and device lifecycle sections

377ba43

make article more guide, less extended doc page

e1e320e

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 5, 2025 06:03 Inactive

david-hernandez-ably approved these changes Dec 5, 2025

View reviewed changes

vladvelici added 2 commits December 8, 2025 09:31

review fixes: pricing paragraph, 4 pillars, java backend example

137c511

spellcheck

98ef717

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 8, 2025 09:56 Inactive

vladvelici requested a review from AndyTWF December 8, 2025 09:57

add hero picture

8b92500

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 8, 2025 10:43 Inactive

AndyTWF reviewed Dec 8, 2025

View reviewed changes

more server-side languages

0f43c50

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 9, 2025 13:33 Inactive

vladvelici added 2 commits December 9, 2025 21:19

php examples everywhere

da18aa0

fixes

6622f0f

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 9, 2025 21:42 Inactive

writing style guide fixes

5306a9f

ably-ci temporarily deployed to ably-docs-push-notifica-gimt7z December 9, 2025 21:48 Inactive

reword without ably paragraph

5636f07

ably-ci deployed to ably-docs-push-notifica-gimt7z December 9, 2025 21:49 View deployment


		Push notification failures are inevitable: devices go offline, users uninstall apps, tokens expire. Monitoring and handling errors properly is critical.

		Ably publishes push errors to a dedicated meta channel `[meta]log:push`. Monitor this channel to track push notification delivery errors.

	* Do not give `publish` capability to clients on channels used for push notifications. This could allow any clients to publish push notifications to that channel.
	* Do not give `publish` capability to clients on channels used for push notifications. This will allow any clients to publish push notifications to that channel.

+              });
+              ```
+              ```java


		Ably publishes delivery feedback to the `[meta]log:push` channel in real-time. This gives you immediate visibility into failures - invalid tokens, expired registrations, platform outages - so you can maintain a clean device registry and debug issues quickly. Ably also handles automatic retries when APNs or FCM experience transient issues, so you don't need to build retry logic yourself.

		## Production-ready checklist


		## Device activation at scale

		Before [devices](/docs/push/configure/device) or [browsers](/docs/push/configure/web) can receive push notifications, they must be activated - registered with both the platform's push service (APNs, FCM, or Web Push) and with Ably. Ably handles the complexity of maintaining these registrations at scale, including token refresh, mapping devices to users, and keeping track of subscriptions to channels.

Add push notifications guide #2983

Are you sure you want to change the base?

Add push notifications guide #2983

Uh oh!

Conversation

vladvelici commented Nov 27, 2025

Description

Checklist

Uh oh!

coderabbitai bot commented Nov 27, 2025

Review skipped

Uh oh!

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!

AndyTWF left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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!

5 participants