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 `