diff --git a/src/data/nav/pubsub.ts b/src/data/nav/pubsub.ts
index 64907e4bad..fc832c1e27 100644
--- a/src/data/nav/pubsub.ts
+++ b/src/data/nav/pubsub.ts
@@ -242,6 +242,10 @@ export default {
{
name: 'Getting started',
pages: [
+ {
+ name: 'Web Push',
+ link: '/docs/push/getting-started/web',
+ },
{
name: 'APNs',
link: '/docs/push/getting-started/apns',
diff --git a/src/images/content/screenshots/getting-started/web-push-getting-started-guide-2.png b/src/images/content/screenshots/getting-started/web-push-getting-started-guide-2.png
new file mode 100644
index 0000000000..9234f07161
Binary files /dev/null and b/src/images/content/screenshots/getting-started/web-push-getting-started-guide-2.png differ
diff --git a/src/images/content/screenshots/getting-started/web-push-getting-started-guide.png b/src/images/content/screenshots/getting-started/web-push-getting-started-guide.png
new file mode 100644
index 0000000000..4ebdfea25d
Binary files /dev/null and b/src/images/content/screenshots/getting-started/web-push-getting-started-guide.png differ
diff --git a/src/pages/docs/push/getting-started/apns.mdx b/src/pages/docs/push/getting-started/apns.mdx
index 3789ca38a3..9d9b66fa34 100644
--- a/src/pages/docs/push/getting-started/apns.mdx
+++ b/src/pages/docs/push/getting-started/apns.mdx
@@ -13,9 +13,11 @@ You'll learn how to set up your `AppDelegate` to manage push notifications, regi
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. Install [Xcode](https://developer.apple.com/xcode/).
-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.
+5. Install [Xcode](https://developer.apple.com/xcode/).
+6. You'll need a real iOS device to test push notifications (the simulator doesn't support APNs).
+7. Set up Apple Push Notification service (APNs) certificates through the [Apple Developer Portal](https://developer.apple.com/).
### (Optional) Install Ably CLI
@@ -197,6 +199,8 @@ func didDeactivateAblyPush(_ error: ARTErrorInfo?) {
```
+Now you are ready to receive push notifications.
+
## Step 3: Receive push notifications
Use `UNUserNotificationCenterDelegate` methods to receive push notifications.
@@ -231,7 +235,7 @@ func userNotificationCenter(_ center: UNUserNotificationCenter,
```
-Push notifications can be sent either directly to your device ID (or client ID),
+Push notifications can be sent either directly to your `deviceId` (or `clientId`),
or posted to a channel, in which case you first need to subscribe your device to that channel:
@@ -266,7 +270,7 @@ func unsubscribeFromChannel(_ channelName: String) {
```
-Sending push notifications using device ID or client ID requires the `push-admin` capability for your API key.
+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).
@@ -554,7 +558,7 @@ with a `push` `extras` field using Ably CLI:
```shell
-ably channels publish --api-key "{{API_KEY}}" exampleChannel1 '{"data":{"foo":"bar","baz":"qux"},"extras":{"push":{"notification":{"title":"Test push","body":"Hello from CLI!"}}}}'
+ably channels publish exampleChannel1 '{"name":"example","data":"Hello from CLI!","extras":{"push":{"notification":{"title":"Ably CLI","body":"Hello from CLI!"},"data":{"foo":"bar"}}}}'
```
@@ -563,10 +567,10 @@ Send the same command again and verify that no notification is received.
You can also send push notifications right from your app. The next step will show you how.
-## Step 5: Send pushes with code
+## Step 5: Send push with code
Just as you can send push notifications through the Ably CLI or dashboard, you can also send them directly from your app
-using device ID (or client ID), or channel publishing methods. For channel publishing, you don't need the admin capabilities
+using `deviceId` (or `clientId`), or channel publishing methods. For channel publishing, you don't need the admin capabilities
for your API key.
Add the following methods to your `AppDelegate` class:
@@ -596,7 +600,7 @@ func sendPushToDevice() {
}
/// Send push notification to a specific client ID
-func sendPushToClientId() {
+func sendPushToClient() {
let recipient = [
"clientId": realtime.auth.clientId ?? "push-tutorial-client"
]
@@ -681,7 +685,7 @@ struct SendPushSection: View {
}
Button(action: {
- appDelegate.sendPushToClientId()
+ appDelegate.sendPushToClient()
statusMessage = "Sending push to client ID..."
}) {
HStack {
diff --git a/src/pages/docs/push/getting-started/web.mdx b/src/pages/docs/push/getting-started/web.mdx
new file mode 100644
index 0000000000..bc75d317bc
--- /dev/null
+++ b/src/pages/docs/push/getting-started/web.mdx
@@ -0,0 +1,743 @@
+---
+title: "Getting started: Web Push Notifications"
+meta_description: "Get started with Ably Push Notifications in JavaScript. Learn how to register a service worker, activate push on your client, handle incoming notifications, and send push messages from the browser."
+meta_keywords: "Push Notifications JavaScript, Ably Push, Web Push, Service Worker, browser push notifications, Ably Push Notifications guide, realtime push JavaScript, push notification example, Ably tutorial JavaScript, device registration, push messaging"
+---
+
+This guide will get you started with Ably Push Notifications in a web application using vanilla JavaScript and a service worker.
+
+You'll learn how to set up an Ably Realtime client with push notification support, register a service worker, activate push notifications, subscribe to channel-based push, send push notifications, and handle incoming notifications in both the service worker and main page.
+
+## Prerequisites
+
+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 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.
+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
+
+Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+
+1. Install the Ably CLI:
+
+
+```shell
+npm install -g @ably/cli
+```
+
+
+2. Run the following to log in to your Ably account and set the default app and API key:
+
+
+```shell
+ably login
+```
+
+
+### Serve your files locally
+
+Service workers require files to be served from a web server (not opened directly as `file://`).
+Navigate to your project directory and use one of the following methods to start a local server:
+
+**Python (built-in on macOS):**
+
+
+```shell
+# Python 3
+python3 -m http.server 8000
+```
+
+
+**Node.js:**
+
+
+```shell
+# Install a simple HTTP server globally
+npm install -g http-server
+
+# Serve the current directory
+http-server -p 8000
+```
+
+
+**PHP:**
+
+
+```shell
+php -S localhost:8000
+```
+
+
+Then open your browser at `http://localhost:8000`.
+
+### Project structure
+
+Your project consists of two files:
+
+- `index.html` — the main page with UI and Ably client logic.
+- `service-worker.js` — the service worker that handles push events and notification clicks.
+
+## Step 1: Set up Ably
+
+This step initializes the Ably Realtime client with the necessary configuration for push notifications, including the API key, client ID, and service worker URL. It also sets up a subscription to the specified channel to listen for incoming messages and log them to the output div.
+
+First, create the `index.html` file with the Ably SDK scripts and a HTML structure for logging messages and displaying status of operations:
+
+
+```html
+
+
+
+
+ Ably Web Push Notifications
+
+
+
+ Ably Web Push Notifications
+
+
+
+
+
+
+
+
+```
+
+
+The two script tags load the Ably Realtime SDK and the Ably Push plugin respectively.
+
+Now add this code inside the empty `