[DX-287] Web push notifications tutorial by maratal · Pull Request #3201 · ably/docs

maratal · 2026-02-13T02:39:16Z

Description

Web push notifications tutorial.

There is also few small fixes for APNs guide as well, let me know if you would like to see it in a different PR.

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-02-13T02:39:22Z

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.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch DX-287-web-push-guide

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

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

AndyTWF · 2026-02-13T10:36:56Z

src/pages/docs/push/getting-started/web.mdx

+1. [Sign up](https://ably.com/signup) for an Ably account.
+2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
+3. Your API key will need the `publish` and `subscribe` capabilities. For sending push notifications from your app, you'll also need the `push-admin` capability.
+4. For channel-based push, add a rule for the channel with **Push notifications enabled** checked. In the dashboard: go to **Pub/Sub** → **Channels** → **Configure** → **Rules** → **Add** or **Edit** a rule,


In the new dashboard, this isn't correct - you select your app then go to the Rules tab in the leftnav

AndyTWF · 2026-02-13T10:39:14Z

src/pages/docs/push/getting-started/web.mdx

+5. A modern browser that supports the [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) (Chrome, Firefox, or Edge recommended). Safari has limited Web Push support.
+6. A local web server to serve your files over `http://localhost` (service workers require a secure context or localhost).
+
+### (Optional) Install Ably CLI <a id="install-cli"/>


There's a CLI PR to add push commands - should we orient the guide more towards using the CLI in that regard? Or at least making it clear you can easily test push sending without any code that way?

ably/ably-cli#126

should we orient the guide more towards using the CLI

I guess so, but when that PR is going to be merged though?

Also re this particular comment, was it triggered by presence of the "(Optional)" prefix in the title? I'm not against removing it - I feel it a bit distracting.

And samples of using CLI here for sending push to device/client are using commands that are not yet released. I'm not sure what to do about that, remove them or wait that PR is merged?

AndyTWF · 2026-02-13T10:41:17Z

src/pages/docs/push/getting-started/web.mdx

+// Initialize Ably connection
+async function getStarted() {
+    realtimeClient = new Ably.Realtime({
+        key: '{{API_KEY}}',


We should call out in a comment here that in production you would never use a key on the client side.

GregHolmes

A good guide @maratal I've left a few comments.
My only other comment is that your IDE seems to wrap text into a new line, where we don't usually do that. It would just be for easier review/developer reading to keep them on the same line for a paragraph.

GregHolmes · 2026-02-23T15:56:18Z

src/pages/docs/push/getting-started/apns.mdx

-5. You'll need a real iOS device to test push notifications (the simulator doesn't support APNs).
-6. Set up Apple Push Notification service (APNs) certificates through the [Apple Developer Portal](https://developer.apple.com/).
+4. For channel-based push, add a rule for the channel with **Push notifications enabled** checked. In the dashboard left sidebar: **Configuration** → **Rules** → **Add** or **Edit** a rule,
+then enable the Push notifications option. See [channel rules](https://ably.com/docs/channels#rules) for details.


Suggested change

then enable the Push notifications option. See [channel rules](https://ably.com/docs/channels#rules) for details.

then enable the Push notifications option. See [channel rules](/docs/channels#rules) for details.

GregHolmes · 2026-02-23T15:57:38Z

src/pages/docs/push/getting-started/web.mdx

+2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
+3. Your API key will need the `publish` and `subscribe` capabilities. For sending push notifications from your app, you'll also need the `push-admin` capability.
+4. For channel-based push, add a rule for the channel with **Push notifications enabled** checked. In the dashboard left sidebar: **Configuration** → **Rules** → **Add** or **Edit** a rule,
+then enable the Push notifications option. See [channel rules](https://ably.com/docs/channels#rules) for details.


Suggested change

then enable the Push notifications option. See [channel rules](https://ably.com/docs/channels#rules) for details.

then enable the Push notifications option. See [channel rules](/docs/channels#rules) for details.

GregHolmes · 2026-02-23T15:58:55Z

src/pages/docs/push/getting-started/web.mdx

+
+Add all the new buttons code to your `HTML` and `<script>` sections:
+
+<Code>


Do we need these 3 to be separate?

Or at least the 2 Javascript ones?

If you merge the 2 JS ones, you would then just need a brief intro to the code in between the html and the one JS.

GregHolmes · 2026-02-23T15:59:27Z

src/pages/docs/push/getting-started/web.mdx

+
+The `extras.push` object has two parts:
+
+- **`notification`**: Contains `title` and `body` that are displayed in the browser notification.


This is quite an AI smell, can we remove the bold from these bullet points? I think if you ask Claude to refer to CLAUDE.md and review this page it'd pick that up.

GregHolmes · 2026-02-23T16:00:04Z

src/pages/docs/push/getting-started/web.mdx

+
+Now you can send push notifications to your device, client, or channel using the buttons in the UI:
+
+![Screenshot of the Swift push tutorial application](../../../../images/content/screenshots/getting-started/web-push-getting-started-guide-2.png)


There are 2 images with the alt: Screenshot of the Swift push tutorial application in this guide. We should adapt this, but we shouldn't really have the same alt for two different images?

GregHolmes · 2026-02-23T16:04:17Z

src/pages/docs/push/getting-started/web.mdx

+Sending push notifications using `deviceId` or `clientId` requires the `push-admin` capability for your API key.
+Use this method for testing purposes. In a production environment, you would typically send push notifications
+from your backend server (by posting messages with `push` `extras` field to a channel).


Suggested change

Sending push notifications using `deviceId` or `clientId` requires the `push-admin` capability for your API key.

Use this method for testing purposes. In a production environment, you would typically send push notifications

from your backend server (by posting messages with `push` `extras` field to a channel).

Sending push notifications using `deviceId` or `clientId` requires the `push-admin` capability for your API key. Use this method for testing purposes. In a production environment, you would typically send push notifications from your backend server (by posting messages with `push` `extras` field to a channel).

GregHolmes · 2026-02-23T16:04:54Z

src/pages/docs/push/getting-started/web.mdx

+from your backend server (by posting messages with `push` `extras` field to a channel).
+
+To test push notifications in your app, you can use [Ably dashboard](https://ably.com/dashboard),
+[Apple developer dashboard](https://icloud.developer.apple.com/dashboard/) or Ably CLI.


Is this part relevant regarding Apple?

GregHolmes · 2026-02-23T16:05:47Z

src/pages/docs/push/getting-started/web.mdx

+
+<Code>
+```javascript
+/// Send push notification to a specific device ID


I think the commenting you're using here is Swift not JS, can we please make sure we follow JS styles?

GregHolmes · 2026-02-23T16:06:40Z

src/pages/docs/push/getting-started/web.mdx

+
+### Handle notification clicks <a id="step-3-notification-clicks"/>
+
+Add a `notificationclick` listener in the same `service-worker.js` to handle what happens when the user taps the notification:


We're using tap here which is usually a mobile term, It'd be better to use click. tap is used twice in this doc.

GregHolmes · 2026-02-23T16:07:52Z

src/pages/docs/push/getting-started/web.mdx

+
+There are also some helper functions to log messages to the output div, show status messages and clear the output log.
+
+## Step 2: Set up push notifications <a id="step-2"/>


Step 4 (UI) is the UI implementation, if a developer runs the code after step 2, they're going to get an error. It may be worth adding an Aside note just stating that the UI part is later in the guide.

maratal · 2026-02-24T15:11:44Z

Hey @GregHolmes, all your comments have been addressed — ready for another look!

- Use relative URLs for internal channel rules links - Add aside note in Step 2 clarifying UI is built in Step 4 - Remove Apple Developer Dashboard reference from web push guide - Merge paired JS code blocks in Steps 4 and 5 into single blocks - Replace triple-slash comments with standard JS double-slash - Remove bold prefixes from bullet list items - Differentiate duplicate image alt text and remove Swift reference - Change 'tap' to 'click' throughout web push guide - Join wrapped paragraph lines for reviewer readability Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Fix sendPushToClientIdBtn typo → sendPushToClientBtn (was a runtime error) - Add const declarations to button variables in Step 5 - Replace **Note:** with <Aside> component in browser compatibility section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

maratal requested review from AndyTWF, GregHolmes and m-hulbert February 13, 2026 02:39

maratal added the review-app Create a Heroku review app label Feb 13, 2026

ably-ci had a problem deploying to ably-docs-dx-287-web-pu-nn8uca February 13, 2026 02:42 Failure

GregHolmes force-pushed the DX-287-web-push-guide branch from 4c7995a to ee20db0 Compare February 13, 2026 10:10

GregHolmes temporarily deployed to ably-docs-dx-287-web-pu-nn8uca February 13, 2026 10:10 Inactive

AndyTWF reviewed Feb 13, 2026

View reviewed changes

maratal force-pushed the DX-287-web-push-guide branch from ee20db0 to 91c271f Compare February 13, 2026 13:15

ably-ci temporarily deployed to ably-docs-dx-287-web-pu-nn8uca February 13, 2026 13:15 Inactive

ably-ci temporarily deployed to ably-docs-dx-287-web-pu-nn8uca February 13, 2026 15:37 Inactive

GregHolmes requested changes Feb 23, 2026

View reviewed changes

maratal force-pushed the DX-287-web-push-guide branch from 7205395 to 94ce859 Compare February 24, 2026 15:28

maratal added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Feb 24, 2026

ably-ci deployed to ably-docs-dx-287-web-pu-wcklwu February 24, 2026 15:30 View deployment

maratal and others added 5 commits February 26, 2026 19:06

Web push notifications tutorial.

cf8aba6

Few refinements and PR feedback address.

d6fa460

Some refinements to swift push guide to fit latest web push changes.

8e306df

maratal force-pushed the DX-287-web-push-guide branch from 94ce859 to 632708e Compare February 26, 2026 18:08

ably-ci had a problem deploying to ably-docs-dx-287-web-pu-wcklwu February 26, 2026 18:49 Failure

	then enable the Push notifications option. See [channel rules](https://ably.com/docs/channels#rules) for details.
	then enable the Push notifications option. See [channel rules](/docs/channels#rules) for details.


		Add all the new buttons code to your `HTML` and `<script>` sections:

		<Code>


		The `extras.push` object has two parts:

		- `notification`: Contains `title` and `body` that are displayed in the browser notification.


		Now you can send push notifications to your device, client, or channel using the buttons in the UI:

		![Screenshot of the Swift push tutorial application](../../../../images/content/screenshots/getting-started/web-push-getting-started-guide-2.png)


		### Handle notification clicks <a id="step-3-notification-clicks"/>

		Add a `notificationclick` listener in the same `service-worker.js` to handle what happens when the user taps the notification:


		There are also some helper functions to log messages to the output div, show status messages and clear the output log.

		## Step 2: Set up push notifications <a id="step-2"/>

Conversation

maratal commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai bot commented Feb 13, 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!

maratal Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

GregHolmes left a comment

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!

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!

maratal commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

maratal commented Feb 13, 2026 •

edited

Loading

coderabbitai bot commented Feb 13, 2026 •

edited

Loading

maratal Feb 13, 2026 •

edited

Loading