From 63cf7cc8e58169035df35d1b329b6da028ec8f3e Mon Sep 17 00:00:00 2001
From: Marat Alekperov <m.alekperov@gmail.com>
Date: Fri, 8 May 2026 17:06:10 +0200
Subject: [PATCH] fix(push-guides): restructure APNs, FCM, and web push guides
 to match react-native/flutter layout

- Add Step 5 "Publish a push notification" with CLI-only publish (client-id + channel sub-steps)
- Remove send-with-code examples from all three guides
- Remove push-admin Aside (info already in prerequisites)
- Align Step 3 opening text across all guides
- Update "send push notifications" to "publish push notifications" throughout
- Restore service worker description sentence in web guide
- APNs Step 6 (location pushes) renumbered from Step 7 after removing send-with-code step

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/pages/docs/push/getting-started/apns.mdx  | 276 ++-----------
 src/pages/docs/push/getting-started/fcm.mdx   | 391 ++++++------------
 .../docs/push/getting-started/flutter.mdx     |  10 +-
 .../push/getting-started/react-native.mdx     |  10 +-
 src/pages/docs/push/getting-started/web.mdx   | 232 ++---------
 5 files changed, 217 insertions(+), 702 deletions(-)

diff --git a/src/pages/docs/push/getting-started/apns.mdx b/src/pages/docs/push/getting-started/apns.mdx
index cce663c4b0..fa8956e98d 100644
--- a/src/pages/docs/push/getting-started/apns.mdx
+++ b/src/pages/docs/push/getting-started/apns.mdx
@@ -6,7 +6,7 @@ meta_keywords: "Push Notifications Swift, Ably Push, APNs, iOS Push, Swift push
 
 This guide will get you started with Ably Push Notifications in a new SwiftUI application.
 
-You'll learn how to set up your `AppDelegate` to manage push notifications, register devices with Ably, send push notifications, subscribe to channel-based push, handle incoming notifications, and implement location-based push notifications.
+You'll learn how to set up your `AppDelegate` to manage push notifications, register devices with Ably, publish push notifications, subscribe to channel-based push, handle incoming notifications, and implement location-based push notifications.
 
 <Aside data-type='note'>
 Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skills) with Agent Skills for all popular AI coding agents. Run `claude plugin add ably/agent-skills` or `npx skills add ably/agent-skills` to get started.
@@ -16,16 +16,16 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 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 [rules](/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/).
+  * Your API key needs the `publish` and `subscribe` capabilities.
+  * Also add the `push-admin` capability if you're using the same API key to publish a push notification. In production this would more likely be a server using a different API key.
+3. Add a rule to a channel so you can test sending push notifications via a channel. Select [**Rules**](https://ably.com/accounts/any/apps/any/app_namespaces) in the Ably dashboard, add a new rule and enable the **Push notifications** option.
+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/).
 
 ### (Optional) Install Ably CLI <a id="install-cli"/>
 
-Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+Use the [Ably CLI](/docs/platform/tools/cli) as an additional client to quickly test Pub/Sub features and push notifications.
 
 1. Install the Ably CLI:
 
@@ -205,7 +205,7 @@ func didDeactivateAblyPush(_ error: ARTErrorInfo?) {
 
 Now you are ready to receive push notifications.
 
-## Step 3: Receive push notifications <a id="step-3"/>
+### Handle push notifications <a id="step-2-handle"/>
 
 Use `UNUserNotificationCenterDelegate` methods to receive push notifications.
 You've set the notification center delegate in the `application:didFinishLaunchingWithOptions` method.
@@ -239,8 +239,9 @@ func userNotificationCenter(_ center: UNUserNotificationCenter,
 ```
 </Code>
 
-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:
+## Step 3: Subscribe to channel push notifications <a id="step-3"/>
+
+To subscribe your device to a channel so it can receive channel-based push notifications, add the following methods to your `AppDelegate` class:
 
 <Code>
 ```swift
@@ -274,23 +275,6 @@ func unsubscribeFromChannel(_ channelName: String) {
 ```
 </Code>
 
-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).
-
-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](/docs/platform/tools/cli).
-
-To publish to your client ID using the [Ably CLI](/docs/platform/tools/cli) paste the following command into your terminal:
-
-<Code>
-```shell
-ably push publish --client-id push-tutorial-client \
-  --title "Test push" \
-  --body "Hello from CLI!" \
-  --data '{"foo":"bar","baz":"qux"}'
-```
-</Code>
-
-For sending pushes via a channel, we need some actual UI to be able to subscribe to this channel. So, let's build one.
-
 ## Step 4: Build the UI <a id="step-4"/>
 
 First, in your `PushTutorialApp.swift`, add `@UIApplicationDelegateAdaptor` wrapped `appDelegate` property
@@ -324,7 +308,7 @@ struct ContentView: View {
     let appDelegate: AppDelegate
 
     @State private var statusMessage = "Ready to start"
-    @State private var selectedChannel = "exampleChannel1"
+    @State private var selectedChannel = "my-first-push-channel"
 
     var body: some View {
         NavigationStack {
@@ -468,8 +452,8 @@ struct SetupPushSection: View {
 // Helper to get a user-friendly title for a channel
 func titleForChannel(_ name: String) -> String {
     let titles = [
-        "exampleChannel1": "Channel 1",
-        "exampleChannel2": "Channel 2"
+        "my-first-push-channel": "Channel 1",
+        "my-first-push-channel-2": "Channel 2"
     ]
     return titles[name] ?? name
 }
@@ -487,11 +471,11 @@ struct ChannelSection: View {
             VStack(spacing: 10) {
                 HStack(spacing: 8) {
                     Menu {
-                        Button(titleForChannel("exampleChannel1")) {
-                            selectedChannel = "exampleChannel1"
+                        Button(titleForChannel("my-first-push-channel")) {
+                            selectedChannel = "my-first-push-channel"
                         }
-                        Button(titleForChannel("exampleChannel2")) {
-                            selectedChannel = "exampleChannel2"
+                        Button(titleForChannel("my-first-push-channel-2")) {
+                            selectedChannel = "my-first-push-channel-2"
                         }
                     } label: {
                         HStack {
@@ -546,217 +530,43 @@ struct ChannelSection: View {
 </Code>
 
 Build and run your app in Xcode on a real device. You will see the UI with sections to activate
-push notifications and subscribe to channels. Tap the "Activate Push" button and wait until the status message
-displays the received device token. Try sending push using client ID or device ID as shown earlier.
-You can get your device ID from the device details button (don't confuse it with the device token):
-
-![Screenshot of the Swift push tutorial application](../../../../images/content/screenshots/getting-started/apns-swift-getting-started-guide.png)
+push notifications and subscribe to channels.
 
-### Send push via channel <a id="step-4-send-channel"/>
-
-To test pushes via channel, subscribe to "Channel 1" in the UI and publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
-
-<Code>
-```shell
-ably push publish --channel exampleChannel1 \
-  --title "Hello" \
-  --body "World!" \
-  --message '{"name":"greeting","data":"Hello World!"}'
-```
-</Code>
-
-If you unsubscribe from this channel in the app's UI, you will no longer receive push notifications for that channel.
-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 push with code <a id="step-5"/>
-
-Just as you can send push notifications through the Ably CLI or dashboard, you can also send them directly from your app
-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:
-
-<Code>
-```swift
-// MARK: - Send Push Notifications
+## Step 5: Publish a push notification <a id="step-5"/>
 
-/// Send push notification to a specific device ID
-func sendPushToDevice() {
-    let recipient = [
-        "deviceId": realtime.device.id
-    ]
-    let data = [
-        "notification": [
-            "title": "Push Tutorial",
-            "body": "Hello from device ID!"
-        ],
-        "data": [
-            "foo": "bar",
-            "baz": "qux"
-        ]
-    ]
-    realtime.push.admin.publish(recipient, data: data) { error in
-        print("Publish result: \(error?.localizedDescription ?? "Success")")
-    }
-}
+Tap **Activate Push** and wait until the status message displays the received device token. You can get your device ID from the **Get Device Details** button (don't confuse it with the device token).
 
-/// Send push notification to a specific client ID
-func sendPushToClient() {
-    let recipient = [
-        "clientId": realtime.auth.clientId ?? "push-tutorial-client"
-    ]
-    let data = [
-        "notification": [
-            "title": "Push Tutorial",
-            "body": "Hello from client ID!"
-        ],
-        "data": [
-            "foo": "bar",
-            "baz": "qux"
-        ]
-    ]
-    realtime.push.admin.publish(recipient, data: data) { error in
-        print("Publish result: \(error?.localizedDescription ?? "Success")")
-    }
-}
-```
-</Code>
+### Publish directly to your device <a id="step-5-direct"/>
 
-Sending to a channel is just publishing a message on a channel with a `push` `extras` field:
+Publish a push notification directly to your client ID (or device ID using `--device-id` instead of `--client-id`) via the [Ably CLI](/docs/platform/tools/cli):
 
-<Code>
-```swift
-/// Send push notification to a specific channel by publishing a message with a push extras field
-func sendPushToChannel(_ channelName: String) {
-    let message = ARTMessage(name: "example", data: "Hello from channel!")
-    message.extras = [
-        "push": [
-            "notification": [
-                "title": "Channel Push",
-                "body": "Sent push to \(channelName)"
-            ],
-            "data": [
-                "foo": "bar",
-                "baz": "qux"
-            ]
-        ]
-    ] as any ARTJsonCompatible
-
-    realtime.channels.get(channelName).publish([message]) { error in
-        if let error {
-            print("Error sending push to \(channelName) with error: \(error.localizedDescription)")
-        } else {
-            print("Sent push to \(channelName)")
-        }
-    }
-}
+<Code fixed="true">
+```shell
+ably push publish --client-id push-tutorial-client \
+  --title "Test push" \
+  --body "Hello from CLI!" \
+  --data '{"foo":"bar","baz":"qux"}'
 ```
 </Code>
 
-Now add buttons for these methods in the new `SendPushSection` view struct:
-
-<Code>
-```swift
-// MARK: - Send Push Section
-
-struct SendPushSection: View {
-    let appDelegate: AppDelegate
-    @Binding var statusMessage: String
-    @Binding var selectedChannel: String
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 12) {
-            Text("Send Push Notifications")
-                .font(.headline)
-
-            VStack(spacing: 10) {
-                Button(action: {
-                    appDelegate.sendPushToDevice()
-                    statusMessage = "Sending push to device ID..."
-                }) {
-                    HStack {
-                        Image(systemName: "phone.badge.checkmark")
-                        Text("Send Push to Device ID")
-                    }
-                    .frame(maxWidth: .infinity)
-                    .padding()
-                    .background(Color.purple)
-                    .foregroundStyle(.white)
-                    .cornerRadius(8)
-                }
-
-                Button(action: {
-                    appDelegate.sendPushToClient()
-                    statusMessage = "Sending push to client ID..."
-                }) {
-                    HStack {
-                        Image(systemName: "person.crop.circle.badge.checkmark")
-                        Text("Send Push to Client ID")
-                    }
-                    .frame(maxWidth: .infinity)
-                    .padding()
-                    .background(Color.orange)
-                    .foregroundStyle(.white)
-                    .cornerRadius(8)
-                }
+### Publish via a channel <a id="step-5-channel"/>
 
-                HStack(spacing: 8) {
-                    Menu {
-                        Button(titleForChannel("exampleChannel1")) {
-                            selectedChannel = "exampleChannel1"
-                        }
-                        Button(titleForChannel("exampleChannel2")) {
-                            selectedChannel = "exampleChannel2"
-                        }
-                    } label: {
-                        HStack {
-                            Image(systemName: "line.3.horizontal.decrease.circle")
-                            Text(titleForChannel(selectedChannel))
-                        }
-                        .frame(maxWidth: .infinity)
-                        .padding()
-                        .background(Color.gray.opacity(0.2))
-                        .cornerRadius(8)
-                    }
+Subscribe to "Channel 1" in the UI, then publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
 
-                    Button(action: {
-                        appDelegate.sendPushToChannel(selectedChannel)
-                        statusMessage = "Sending push to channel: \(selectedChannel)..."
-                    }) {
-                        HStack {
-                            Image(systemName: "checkmark.circle.fill")
-                            Text("Send")
-                        }
-                        .frame(maxWidth: .infinity)
-                        .padding()
-                        .background(Color.cyan)
-                        .foregroundStyle(.white)
-                        .cornerRadius(8)
-                    }
-                }
-            }
-        }
-        .padding()
-        .background(Color.white)
-        .cornerRadius(12)
-        .shadow(radius: 2)
-    }
-}
+<Code fixed="true">
+```shell
+ably push publish --channel my-first-push-channel \
+  --title "Hello" \
+  --body "World!" \
+  --message '{"name":"greeting","data":"Hello World!"}'
 ```
 </Code>
 
-Update your `ContentView` body to include this section (add it just after the `ChannelSection`):
+![Screenshot of the Swift push tutorial application](../../../../images/content/screenshots/getting-started/apns-swift-getting-started-guide.png)
 
-<Code>
-```swift
-// Send Push Section
-SendPushSection(appDelegate: appDelegate, statusMessage: $statusMessage, selectedChannel: $selectedChannel)
-```
-</Code>
+If you unsubscribe from this channel in the app's UI, you will no longer receive push notifications for that channel. Run the same command again and verify that no notification is received.
 
-Build and run your app again. Use the added section to send push notifications.
+To see the full list of options for publishing push notifications with the Ably CLI, run `ably push publish --help` or see the [Ably CLI push documentation](/docs/cli/push). To publish push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
 
 ## Step 6: Location pushes <a id="step-6"/>
 
@@ -769,7 +579,7 @@ Add `Location (when in use)`, `Location (Always)`, `Location Push Service Extens
 Add `Location Push Service Extension` target as described at the [Apple Developer Portal](https://developer.apple.com/documentation/CoreLocation/creating-a-location-push-service-extension).
 For simplicity, use **Automatically manage signing**, so all needed identifiers are created for you by
 Xcode (with XC prefix in their display name). Your Location Push Service Extension should have a bundle
-identifier of your app with a suffix of extension's product name (e.g., `the.company.TheApp.TheExtension`).
+identifier of your app with a suffix of extension's product name (for example, `the.company.TheApp.TheExtension`).
 
 Add these methods to your `AppDelegate` class:
 
@@ -861,7 +671,7 @@ func didUpdateAblyPush(_ error: ARTErrorInfo?) {
 ```
 </Code>
 
-### Receiving location pushes <a id="step-5-receiving"/>
+### Receive location pushes <a id="step-6-receiving"/>
 
 Once you've added the location push extension to your project, Xcode gives you a default implementation of the
 `LocationPushService.swift` file in your extension target.
diff --git a/src/pages/docs/push/getting-started/fcm.mdx b/src/pages/docs/push/getting-started/fcm.mdx
index bea7cd82be..dd3979a208 100644
--- a/src/pages/docs/push/getting-started/fcm.mdx
+++ b/src/pages/docs/push/getting-started/fcm.mdx
@@ -6,7 +6,7 @@ meta_keywords: "Push Notifications Kotlin, Ably Push, FCM, Android Push, Kotlin
 
 This guide will get you started with Ably Push Notifications in a new Android application using Kotlin.
 
-You'll learn how to set up your application with Firebase Cloud Messaging (FCM), register devices with Ably, send push notifications, subscribe to channel-based push, and handle incoming notifications.
+You'll learn how to set up your application with Firebase Cloud Messaging (FCM), register devices with Ably, publish push notifications, subscribe to channel-based push, and handle incoming notifications.
 
 <Aside data-type='note'>
 Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skills) with Agent Skills for all popular AI coding agents. Run `claude plugin add ably/agent-skills` or `npx skills add ably/agent-skills` to get started.
@@ -16,14 +16,15 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 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 needs 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 [rules](/docs/channels#rules) for details.
-5. Install [Android Studio](https://developer.android.com/studio).
-6. Use a real Android device or an emulator with Google Play Services installed (required for FCM).
+  * Your API key needs the `publish` and `subscribe` capabilities.
+  * Also add the `push-admin` capability if you're using the same API key to publish a push notification. In production this would more likely be a server using a different API key.
+3. Add a rule to a channel so you can test sending push notifications via a channel. Select [**Rules**](https://ably.com/accounts/any/apps/any/app_namespaces) in the Ably dashboard, add a new rule and enable the **Push notifications** option.
+4. Install [Android Studio](https://developer.android.com/studio).
+5. Use a real Android device or an emulator with Google Play Services installed (required for FCM).
 
 ### (Optional) Install Ably CLI <a id="install-cli"/>
 
-Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+Use the [Ably CLI](/docs/platform/tools/cli) as an additional client to quickly test Pub/Sub features and push notifications.
 
 1. Install the Ably CLI:
 
@@ -162,91 +163,7 @@ Register your `Application` class in `AndroidManifest.xml` inside the `<applicat
 
 ## Step 2: Set up push notifications <a id="step-2"/>
 
-To receive push notifications on Android, you need to integrate with FCM. Create a `PushNotificationService.kt` file that extends `FirebaseMessagingService`. This service handles new FCM tokens and incoming push messages:
-
-<Code>
-```kotlin
-import android.app.NotificationChannel
-import android.app.NotificationManager
-import android.os.Build
-import android.util.Log
-import androidx.core.app.NotificationCompat
-import com.google.firebase.messaging.FirebaseMessagingService
-import com.google.firebase.messaging.RemoteMessage
-import io.ably.lib.types.RegistrationToken
-
-class PushNotificationService : FirebaseMessagingService() {
-
-    companion object {
-        private const val TAG = "PushService"
-        private const val CHANNEL_ID = "push_tutorial_channel"
-    }
-
-    override fun onNewToken(token: String) {
-        super.onNewToken(token)
-        Log.d(TAG, "New FCM token received")
-        try {
-            // Update the FCM token on Ably server
-            AblyHelper.getInstance().push.getActivationContext().onNewRegistrationToken(RegistrationToken.Type.FCM, token)
-        } catch (e: Exception) {
-            Log.e(TAG, "Error updating FCM token with Ably", e)
-        }
-    }
-
-    override fun onMessageReceived(remoteMessage: RemoteMessage) {
-        super.onMessageReceived(remoteMessage)
-        Log.d(TAG, "Message received from: ${remoteMessage.from}")
-
-        // Display a notification when the app is in the foreground
-        remoteMessage.notification?.let { notification ->
-            showNotification(
-                notification.title ?: "Push Notification",
-                notification.body ?: "",
-                remoteMessage.data
-            )
-        }
-    }
-
-    private fun showNotification(title: String, body: String, data: Map<String, String>) {
-        val notificationManager = getSystemService(NOTIFICATION_SERVICE) as NotificationManager
-
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            val channel = NotificationChannel(
-                CHANNEL_ID,
-                "Push Tutorial",
-                NotificationManager.IMPORTANCE_DEFAULT
-            )
-            notificationManager.createNotificationChannel(channel)
-        }
-
-        val notification = NotificationCompat.Builder(this, CHANNEL_ID)
-            .setSmallIcon(android.R.drawable.ic_dialog_info)
-            .setContentTitle(title)
-            .setContentText(body)
-            .setAutoCancel(true)
-            .build()
-
-        notificationManager.notify(System.currentTimeMillis().toInt(), notification)
-    }
-}
-```
-</Code>
-
-Register the service in `AndroidManifest.xml` inside the `<application>` element:
-
-<Code>
-```xml
-<service
-    android:name=".PushNotificationService"
-    android:exported="false">
-    <intent-filter>
-        <action android:name="com.google.firebase.MESSAGING_EVENT" />
-    </intent-filter>
-</service>
-```
-</Code>
-
-Now add push activation and deactivation to your `MainActivity.kt`. The Ably Android SDK activates push asynchronously and the result arrives via Android's broadcast system, so register a `BroadcastReceiver` to handle it (the following imports cover all steps in this guide):
+Add push activation and deactivation to your `MainActivity.kt`. The Ably Android SDK activates push asynchronously and the result arrives via Android's broadcast system, so register a `BroadcastReceiver` to handle it (the following imports cover all steps in this guide):
 
 <Code>
 ```kotlin
@@ -275,7 +192,7 @@ class MainActivity : AppCompatActivity() {
 
     companion object {
         private const val TAG = "MainActivity"
-        private const val CHANNEL_NAME = "exampleChannel1"
+        private const val CHANNEL_NAME = "my-first-push-channel"
     }
 
     private val realtime by lazy { AblyHelper.getInstance() }
@@ -342,9 +259,95 @@ class MainActivity : AppCompatActivity() {
 
 Your app is now configured to receive push notifications once activated.
 
-## Step 3: Subscribe and test push notifications <a id="step-3"/>
+### Handle push notifications <a id="step-2-handle"/>
 
-Push notifications delivered while your app is in the background are handled automatically by the FCM SDK and displayed as system notifications. For foreground handling, your `PushNotificationService.onMessageReceived()` method (from Step 2) displays a notification via `NotificationManager`.
+Create a `PushNotificationService.kt` file that extends `FirebaseMessagingService`. This service handles new FCM tokens and incoming push messages:
+
+<Code>
+```kotlin
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+import io.ably.lib.types.RegistrationToken
+
+class PushNotificationService : FirebaseMessagingService() {
+
+    companion object {
+        private const val TAG = "PushService"
+        private const val CHANNEL_ID = "push_tutorial_channel"
+    }
+
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        Log.d(TAG, "New FCM token received")
+        try {
+            // Update the FCM token on Ably server
+            AblyHelper.getInstance().push.getActivationContext().onNewRegistrationToken(RegistrationToken.Type.FCM, token)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error updating FCM token with Ably", e)
+        }
+    }
+
+    override fun onMessageReceived(remoteMessage: RemoteMessage) {
+        super.onMessageReceived(remoteMessage)
+        Log.d(TAG, "Message received from: ${remoteMessage.from}")
+
+        // Display a notification when the app is in the foreground
+        remoteMessage.notification?.let { notification ->
+            showNotification(
+                notification.title ?: "Push Notification",
+                notification.body ?: "",
+                remoteMessage.data
+            )
+        }
+    }
+
+    private fun showNotification(title: String, body: String, data: Map<String, String>) {
+        val notificationManager = getSystemService(NOTIFICATION_SERVICE) as NotificationManager
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID,
+                "Push Tutorial",
+                NotificationManager.IMPORTANCE_DEFAULT
+            )
+            notificationManager.createNotificationChannel(channel)
+        }
+
+        val notification = NotificationCompat.Builder(this, CHANNEL_ID)
+            .setSmallIcon(android.R.drawable.ic_dialog_info)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setAutoCancel(true)
+            .build()
+
+        notificationManager.notify(System.currentTimeMillis().toInt(), notification)
+    }
+}
+```
+</Code>
+
+Register the service in `AndroidManifest.xml` inside the `<application>` element:
+
+<Code>
+```xml
+<service
+    android:name=".PushNotificationService"
+    android:exported="false">
+    <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+    </intent-filter>
+</service>
+```
+</Code>
+
+Push notifications delivered while your app is in the background are handled automatically by the FCM SDK and displayed as system notifications. The `onMessageReceived()` method handles foreground notifications via `NotificationManager`.
+
+## Step 3: Subscribe to channel push notifications <a id="step-3"/>
 
 To subscribe your device to a channel so it can receive channel-based push notifications, add the following methods to `MainActivity`:
 
@@ -395,33 +398,6 @@ fun subscribeToRealtime(channelName: String) {
 ```
 </Code>
 
-<Aside>
-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).
-</Aside>
-
-Now use the [Ably CLI](/docs/platform/tools/cli) to test publishing a push notification to your client ID:
-
-<Code>
-```shell
-ably push publish --client-id push-tutorial-client \
-  --title "Test push" \
-  --body "Hello from CLI!" \
-  --data '{"foo":"bar","baz":"qux"}'
-```
-</Code>
-
-Or send directly to a device ID:
-
-<Code>
-```shell
-ably push publish --device-id <your-device-id> \
-  --title "Test push" \
-  --body "Hello from device ID!"
-```
-</Code>
-
-To send push notifications via a channel, you first need a UI to subscribe to the channel.
-
 ## Step 4: Build the UI <a id="step-4"/>
 
 Create the layout file `res/layout/activity_main.xml`:
@@ -517,7 +493,7 @@ class MainActivity : AppCompatActivity() {
 
     companion object {
         private const val TAG = "MainActivity"
-        private const val CHANNEL_NAME = "exampleChannel1"
+        private const val CHANNEL_NAME = "my-first-push-channel"
     }
 
     private val realtime by lazy { AblyHelper.getInstance() }
@@ -656,170 +632,43 @@ class MainActivity : AppCompatActivity() {
 ```
 </Code>
 
-Build and run your app on an Android device or emulator. Tap **Activate Push** and wait until the status message displays your device ID. Try sending a push using the Ably CLI commands shown in Step 3.
-
-### Send push via channel <a id="step-4-send-channel"/>
-
-To test push notifications via channel, tap **Subscribe to Channel** in the app and then publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
-
-<Code>
-```shell
-ably push publish --channel exampleChannel1 \
-  --title "Hello" \
-  --body "World!" \
-  --message '{"name":"greeting","data":"Hello World!"}'
-```
-</Code>
-
-![Screenshot of the Kotlin push tutorial application](../../../../images/content/screenshots/getting-started/fcm-push-getting-started-guide.png)
-
-If you tap **Unsubscribe from Channel**, you will no longer receive push notifications for that channel. 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.
+Build and run your app on an Android device or emulator.
 
-## Step 5: Send push with code <a id="step-5"/>
+## Step 5: Publish a push notification <a id="step-5"/>
 
-Just as you can send push notifications through the Ably CLI or dashboard, you can also send them directly from your app using `deviceId` (or `clientId`), or channel publishing methods. For channel publishing, you don't need the admin capabilities for your API key.
+In the app, tap **Activate Push** and wait until the status message displays your device ID.
 
-Add the following methods to `MainActivity`:
+### Publish directly to your device <a id="step-5-direct"/>
 
-<Code>
-```kotlin
-fun sendPushToDevice() {
-    val deviceId = realtime.device().id
-    val recipient = arrayOf(Param("deviceId", deviceId))
-    val payload = JsonObject().apply {
-        add("notification", JsonObject().apply {
-            addProperty("title", "Push Tutorial")
-            addProperty("body", "Hello from device ID!")
-        })
-        add("data", JsonObject().apply {
-            addProperty("foo", "bar")
-            addProperty("baz", "qux")
-        })
-    }
-
-    realtime.push.admin.publishAsync(recipient, payload, object : CompletionListener {
-        override fun onSuccess() {
-            updateStatus("Push sent to device ID: $deviceId")
-        }
-        override fun onError(reason: ErrorInfo?) {
-            updateStatus("Failed to send push to device: ${reason?.message}")
-        }
-    })
-}
+Publish a push notification directly to your client ID (or device ID using `--device-id` instead of `--client-id`) via the [Ably CLI](/docs/platform/tools/cli):
 
-fun sendPushToClient() {
-    val clientId = realtime.auth.clientId
-    val recipient = arrayOf(Param("clientId", clientId))
-    val payload = JsonObject().apply {
-        add("notification", JsonObject().apply {
-            addProperty("title", "Push Tutorial")
-            addProperty("body", "Hello from client ID!")
-        })
-        add("data", JsonObject().apply {
-            addProperty("foo", "bar")
-            addProperty("baz", "qux")
-        })
-    }
-
-    realtime.push.admin.publishAsync(recipient, payload, object : CompletionListener {
-        override fun onSuccess() {
-            updateStatus("Push sent to client ID: $clientId")
-        }
-        override fun onError(reason: ErrorInfo?) {
-            updateStatus("Failed to send push to client: ${reason?.message}")
-        }
-    })
-}
+<Code fixed="true">
+```shell
+ably push publish --client-id push-tutorial-client \
+  --title "Test push" \
+  --body "Hello from CLI!" \
+  --data '{"foo":"bar","baz":"qux"}'
 ```
 </Code>
 
-Sending to a channel is just publishing a message on a channel with a `push` `extras` field:
+### Publish via a channel <a id="step-5-channel"/>
 
-<Code>
-```kotlin
-fun sendPushToChannel(channelName: String) {
-    val extras = JsonObject().apply {
-        add("push", JsonObject().apply {
-            add("notification", JsonObject().apply {
-                addProperty("title", "Channel Push")
-                addProperty("body", "Sent push to $channelName")
-            })
-            add("data", JsonObject().apply {
-                addProperty("foo", "bar")
-                addProperty("baz", "qux")
-            })
-        })
-    }
-
-    val message = Message("example", "Hello from channel!")
-    message.extras = MessageExtras(extras)
-
-    realtime.channels.get(channelName).publish(message, object : CompletionListener {
-        override fun onSuccess() {
-            updateStatus("Push sent to channel: $channelName")
-        }
-        override fun onError(reason: ErrorInfo?) {
-            updateStatus("Failed to send push to channel: ${reason?.message}")
-        }
-    })
-}
-```
-</Code>
-
-Add three more buttons to `activity_main.xml` (before the `ScrollView`):
+Tap **Subscribe to Channel** in the app, then publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
 
-<Code>
-```xml
-<Button
-    android:id="@+id/sendToDeviceBtn"
-    android:layout_width="match_parent"
-    android:layout_height="wrap_content"
-    android:text="Send Push to Device"
-    android:textColor="#FFFFFF"
-    android:backgroundTint="#6610F2"
-    android:layout_marginBottom="8dp" />
-
-<Button
-    android:id="@+id/sendToClientBtn"
-    android:layout_width="match_parent"
-    android:layout_height="wrap_content"
-    android:text="Send Push to Client"
-    android:textColor="#FFFFFF"
-    android:backgroundTint="#20C997"
-    android:layout_marginBottom="8dp" />
-
-<Button
-    android:id="@+id/sendToChannelBtn"
-    android:layout_width="match_parent"
-    android:layout_height="wrap_content"
-    android:text="Send Push to Channel"
-    android:textColor="#FFFFFF"
-    android:backgroundTint="#17A2B8"
-    android:layout_marginBottom="16dp" />
+<Code fixed="true">
+```shell
+ably push publish --channel my-first-push-channel \
+  --title "Hello" \
+  --body "World!" \
+  --message '{"name":"greeting","data":"Hello World!"}'
 ```
 </Code>
 
-Wire up the new buttons in `MainActivity.onCreate()`:
-
-<Code>
-```kotlin
-findViewById<Button>(R.id.sendToDeviceBtn).setOnClickListener {
-    sendPushToDevice()
-}
-findViewById<Button>(R.id.sendToClientBtn).setOnClickListener {
-    sendPushToClient()
-}
-findViewById<Button>(R.id.sendToChannelBtn).setOnClickListener {
-    sendPushToChannel(CHANNEL_NAME)
-}
-```
-</Code>
+![Screenshot of the Kotlin push tutorial application](../../../../images/content/screenshots/getting-started/fcm-push-getting-started-guide.png)
 
-Build and run your app again. Use the new buttons to send push notifications directly to your device ID, client ID, or the subscribed channel:
+If you tap **Unsubscribe from Channel**, you will no longer receive push notifications for that channel. Run the same command again and verify that no notification is received.
 
-![Screenshot of the Kotlin push tutorial application](../../../../images/content/screenshots/getting-started/fcm-push-getting-started-guide-2.png)
+To see the full list of options for publishing push notifications with the Ably CLI, run `ably push publish --help` or see the [Ably CLI push documentation](/docs/cli/push). To publish push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
 
 ## Next steps <a id="next-steps"/>
 
diff --git a/src/pages/docs/push/getting-started/flutter.mdx b/src/pages/docs/push/getting-started/flutter.mdx
index 286a2a1ad1..201d9fd95d 100644
--- a/src/pages/docs/push/getting-started/flutter.mdx
+++ b/src/pages/docs/push/getting-started/flutter.mdx
@@ -6,21 +6,21 @@ meta_keywords: "Push Notifications Flutter, Ably Push, FCM, APNs, Flutter push n
 
 This guide will get you started with Ably Push Notifications in a Flutter application targeting Android and iOS.
 
-You'll learn how to configure Firebase Cloud Messaging (FCM) for Android and APNs for iOS, register devices with Ably, send push notifications, subscribe to channel-based push, and handle incoming notifications.
+You'll learn how to configure Firebase Cloud Messaging (FCM) for Android and APNs for iOS, register devices with Ably, publish push notifications, subscribe to channel-based push, and handle incoming notifications.
 
 ## Prerequisites <a id="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.
   * Your API key needs the `publish`, `subscribe` capabilities.
-  * Also add the `push-admin` capability if you're using the same API key to send a push notification. In production this would more likely be a server using a different API key.
+  * Also add the `push-admin` capability if you're using the same API key to publish a push notification. In production this would more likely be a server using a different API key.
 3. Add a rule to a channel so you can test sending push notification via a channel. Select [**Rules**](https://ably.com/accounts/any/apps/any/app_namespaces) in the Ably dashboard, add a new rule and enable the **Push notifications** option.
 4. Install the [Flutter SDK](https://docs.flutter.dev/get-started/install).
 5. Use a real device or an emulator with Google Play Services installed (required for FCM on Android), or a real iOS device or simulator (Xcode 14+) for APNs.
 
 ### (Optional) Install Ably CLI <a id="install-cli"/>
 
-Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+Use the [Ably CLI](/docs/platform/tools/cli) as an additional client to quickly test Pub/Sub features and push notifications.
 
 1. Install the Ably CLI:
 
@@ -478,9 +478,9 @@ ably push publish --channel my-first-push-channel \
 ```
 </Code>
 
-If you tap **Unsubscribe from Channel**, the device no longer receives push notifications for that channel. Send the same command again and verify that no notification is received.
+If you tap **Unsubscribe from Channel**, the device no longer receives push notifications for that channel. Run the same command again and verify that no notification is received.
 
-To see the full list of push publishing options with the Ably CLI, run `ably push publish --help` in your terminal or visit the [Ably CLI push commands](/docs/cli/push) page. To send push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
+To see the full list of push publishing options with the Ably CLI, run `ably push publish --help` in your terminal or visit the [Ably CLI push commands](/docs/cli/push) page. To publish push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
 
 ![Screenshot of the Flutter push tutorial application](../../../../images/content/screenshots/getting-started/flutter-push-getting-started-guide.png)
 
diff --git a/src/pages/docs/push/getting-started/react-native.mdx b/src/pages/docs/push/getting-started/react-native.mdx
index 625c5c877e..9e765f814a 100644
--- a/src/pages/docs/push/getting-started/react-native.mdx
+++ b/src/pages/docs/push/getting-started/react-native.mdx
@@ -6,14 +6,14 @@ meta_keywords: "Push Notifications React Native, Ably Push, FCM, Android Push, i
 
 This guide will get you started with Ably Push Notifications in a new React Native application.
 
-You'll learn how to set up your application with Firebase Cloud Messaging (FCM), register devices with Ably, send push notifications, subscribe to channel-based push, and handle incoming notifications on both iOS and Android.
+You'll learn how to set up your application with Firebase Cloud Messaging (FCM), register devices with Ably, publish push notifications, subscribe to channel-based push, and handle incoming notifications on both iOS and Android.
 
 ## Prerequisites <a id="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.
   * Your API key needs the `publish`, `subscribe` capabilities.
-  * Also add the `push-admin` capability if you're using the same API key to send a push notification. In production this would more likely be a server using a different API key.
+  * Also add the `push-admin` capability if you're using the same API key to publish a push notification. In production this would more likely be a server using a different API key.
 3. Add a rule to a channel so you can test sending push notification via a channel. Select [**Rules**](https://ably.com/accounts/any/apps/any/app_namespaces) in the Ably dashboard, add a new rule and enable the **Push notifications** option.
 4. Install [Node.js](https://nodejs.org/) 18 or higher.
 5. Set up your React Native development environment following the [React Native CLI Quickstart](https://reactnative.dev/docs/set-up-your-environment).
@@ -330,7 +330,7 @@ async function deactivatePush() {
 3. Registers the device with Ably's push notification service using the token.
 4. Sets up a listener for FCM token refresh events to update the registration with Ably if the token changes.
 
-After successful activation, `deviceId` can be used to send push notifications to this device.
+After successful activation, `deviceId` can be used to publish push notifications to this device.
 
 <Aside data-type='note'>
 In React Native `realtime.push.activate()` is not used because it's a JS SDK and it registers browser for push notifications, which is not what you want in a React Native app. Instead, use `realtime.push.admin.deviceRegistrations` API to register the device.
@@ -502,9 +502,9 @@ ably push publish --channel my-first-push-channel \
 ```
 </Code>
 
-If you tap **Unsubscribe from Channel**, the device no longer receives push notifications for that channel. Send the same command again and verify that no notification is received.
+If you tap **Unsubscribe from Channel**, the device no longer receives push notifications for that channel. Run the same command again and verify that no notification is received.
 
-To see the full list of options for sending push notifications with the Ably CLI, run `ably push publish --help` or see the [Ably CLI push documentation](/docs/cli/push). To send push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
+To see the full list of options for publishing push notifications with the Ably CLI, run `ably push publish --help` or see the [Ably CLI push documentation](/docs/cli/push). To publish push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
 
 ![Screenshot of the React Native push tutorial application](../../../../images/content/screenshots/getting-started/react-native-push-getting-started-guide.png)
 
diff --git a/src/pages/docs/push/getting-started/web.mdx b/src/pages/docs/push/getting-started/web.mdx
index 74dd7da117..d72715dfb6 100644
--- a/src/pages/docs/push/getting-started/web.mdx
+++ b/src/pages/docs/push/getting-started/web.mdx
@@ -6,7 +6,7 @@ meta_keywords: "Push Notifications JavaScript, Ably Push, Web Push, Service Work
 
 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.
+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, publish push notifications, and handle incoming notifications in both the service worker and main page.
 
 <Aside data-type='note'>
 Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skills) with Agent Skills for all popular AI coding agents. Run `claude plugin add ably/agent-skills` or `npx skills add ably/agent-skills` to get started.
@@ -16,19 +16,19 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 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 [rules](/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).
+  * Your API key needs the `publish`, `subscribe` capabilities.
+  * Also add the `push-admin` capability if you're using the same API key to publish a push notification. In production this would more likely be a server using a different API key.
+3. Add a rule to a channel so you can test sending push notification via a channel. Select [**Rules**](https://ably.com/accounts/any/apps/any/app_namespaces) in the Ably dashboard, add a new rule and enable the **Push notifications** option.
+4. 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.
+5. 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"/>
 
-Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+Use the [Ably CLI](/docs/platform/tools/cli) as an additional client to quickly test Pub/Sub features and push notifications.
 
 1. Install the Ably CLI:
 
-<Code>
+<Code fixed="true">
 ```shell
 npm install -g @ably/cli
 ```
@@ -36,7 +36,7 @@ npm install -g @ably/cli
 
 2. Run the following to log in to your Ably account and set the default app and API key:
 
-<Code>
+<Code fixed="true">
 ```shell
 ably login
 ```
@@ -49,7 +49,7 @@ Navigate to your project directory and use one of the following methods to start
 
 **Python (built-in on macOS):**
 
-<Code>
+<Code fixed="true">
 ```shell
 # Python 3
 python3 -m http.server 8000
@@ -58,7 +58,7 @@ python3 -m http.server 8000
 
 **Node.js:**
 
-<Code>
+<Code fixed="true">
 ```shell
 # Install a simple HTTP server globally
 npm install -g http-server
@@ -70,7 +70,7 @@ http-server -p 8000
 
 **PHP:**
 
-<Code>
+<Code fixed="true">
 ```shell
 php -S localhost:8000
 ```
@@ -126,7 +126,7 @@ Now add this code inside the empty `<script>` tag to initialize the Ably client
 
 <Code>
 ```javascript
-const channelName = 'exampleChannel1';
+const channelName = 'my-first-push-channel';
 
 let realtimeClient;
 let channel;
@@ -241,22 +241,16 @@ async function deactivatePush() {
 
 When `realtimeClient.push.activate()` is called, the Ably SDK will:
 
-1. Register the service worker specified in `pushServiceWorkerUrl` (more on this in the next section).
+1. Register the service worker specified in `pushServiceWorkerUrl`.
 2. Request notification permission from the user (the browser will show a permission prompt).
 3. Obtain a push subscription from the browser's Push API.
 4. Register the device with Ably's push notification service.
 
 After successful activation, `realtimeClient.device().id` contains the unique device ID assigned by Ably.
 
-## Step 3: Receive push notifications <a id="step-3"/>
-
-Service worker is a key part of the push notifications workflow for web browsers. It's a JavaScript file that runs in the background and can receive push notifications even when the page is not open.
+A service worker is a key part of the push notifications workflow for web browsers. It's a JavaScript file that runs in the background and can receive push notifications even when the page is not open. Create a `service-worker.js` file in the root of your project.
 
-### Create the service worker <a id="step-3-service-worker"/>
-
-Create a `service-worker.js` file in the root of your project.
-
-The service worker listens for `push` events and displays a notification using `self.registration.showNotification()`. It can also forward the notification data to any open pages of your application via `client.postMessage()` (optional, for demonstration purposes, since you have a realtime subscription to the channel):
+The service worker listens for `push` events and displays a notification using `self.registration.showNotification()`. It can also forward the notification data to any open pages via `client.postMessage()`:
 
 <Code>
 ```javascript
@@ -289,15 +283,6 @@ self.addEventListener("push", (event) => {
 ```
 </Code>
 
-Key points about the service worker:
-
-- `event.data.json()` — parses the push message payload sent by the server.
-- `self.registration.showNotification()` — displays a native browser notification.
-- `client.postMessage()` — sends data to open pages of your application.
-- `push` events can only be handled in a service worker, not in the main page.
-
-### 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 clicks the notification:
 
 <Code>
@@ -339,18 +324,11 @@ self.addEventListener('notificationclick', function(event) {
 ```
 </Code>
 
-When a notification is clicked, the service worker handler does the following:
+When a notification is clicked, the handler closes the notification, looks for an existing window, sends it the notification data via `postMessage`, and focuses it. If no window exists, it opens a new one.
 
-1. Closes the notification.
-2. Looks for an existing window/tab for the app.
-3. If found, sends the notification data via `postMessage` and focuses the window.
-4. If no window exists, opens a new one.
+### Handle push notifications <a id="step-2-handle"/>
 
-Note that `event.notification` (a `Notification` object) is not serializable, so you must extract individual properties before sending via `postMessage`.
-
-### Handle notifications from the service worker <a id="step-3-handle-notifications"/>
-
-Back in your `index.html`, add a listener to receive messages from the service worker. This lets you update the page UI when a push notification is received or clicked. You can add it anywhere in the `<script>` section (for example, before the `getStarted()` call):
+Back in your `index.html`, add a listener to receive messages from the service worker. This lets you update the page UI when a push notification is received or clicked. Add it anywhere in the `<script>` section (for example, before the `getStarted()` call):
 
 <Code>
 ```javascript
@@ -373,9 +351,9 @@ navigator.serviceWorker.addEventListener('message', event => {
 ```
 </Code>
 
-### Channel push notifications <a id="step-3-subscribe-channel"/>
+## Step 3: Subscribe to channel push notifications <a id="step-3"/>
 
-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:
+To subscribe your device to a channel so it can receive channel-based push notifications, add the following functions to your `<script>` tag:
 
 <Code>
 ```javascript
@@ -403,26 +381,9 @@ async function unsubscribeFromChannel() {
 ```
 </Code>
 
-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).
-
-To test push notifications in your app, you can use [Ably dashboard](https://ably.com/dashboard) or [Ably CLI](/docs/platform/tools/cli).
-
-To publish to your client using the [Ably CLI](/docs/platform/tools/cli) paste the following command into your terminal:
-
-<Code>
-```shell
-ably push publish --client-id push-tutorial-client \
-  --title "Test push" \
-  --body "Hello from CLI!" \
-  --data '{"foo":"bar","baz":"qux"}'
-```
-</Code>
-
-For sending pushes via a channel, we need some actual UI to be able to subscribe to this channel. So, let's build one.
-
 ## Step 4: Build the UI <a id="step-4"/>
 
-Add the following HTML structure to the `index.html` file before `output-container` div:
+Add the following HTML structure to the `index.html` file before the `output-container` div:
 
 <Code>
 ```html
@@ -563,150 +524,45 @@ button:disabled {
 ```
 </Code>
 
-Save all the files and open `http://localhost:8000` in your browser (you might want to clear the browser's cache if it's not your first time running the project).
-You will see the UI with buttons to activate push notifications and subscribe to the channel.
-Click the "Activate Push" button and wait until the log message with the `deviceId` is displayed.
-Try sending push using this `deviceId` or `clientId` as shown earlier.
+Save all the files and open `http://localhost:8000` in your browser (you might want to clear the browser's cache if it's not your first time running the project). You will see the UI with buttons to activate push notifications and subscribe to the channel.
 
-### Send push via channel <a id="step-4-send-channel"/>
+## Step 5: Publish a push notification <a id="step-5"/>
 
-To test pushes via channel, subscribe to the channel in the UI and publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
+In the app click **Activate Push** and wait until the log message with the device ID is displayed.
 
-<Code>
+### Publish directly to your device <a id="step-5-direct"/>
+
+Publish a push notification directly to your client ID (or device ID using `--device-id` instead of `--client-id`) via the [Ably CLI](/docs/platform/tools/cli):
+
+<Code fixed="true">
 ```shell
-ably push publish --channel exampleChannel1 \
+ably push publish --client-id push-tutorial-client \
   --title "Hello" \
   --body "World!" \
-  --message '{"name":"greeting","data":"Hello World!"}'
-```
-</Code>
-
-Here you can see the first push sent to the `deviceId`. And the second one published to the channel together with the realtime message:
-
-![Screenshot of the web push tutorial application showing push notifications received](../../../../images/content/screenshots/getting-started/web-push-getting-started-guide.png)
-
-If you unsubscribe from this channel in the app's UI, you will no longer receive push notifications for that channel.
-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 push with code <a id="step-5"/>
-
-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 for your API key.
-
-Add the following methods to your `<script>` section:
-
-<Code>
-```javascript
-// Send push notification to a specific device ID
-async function sendPushToDevice() {
-    try {
-        const deviceId = realtimeClient.device().id;
-        await realtimeClient.push.admin.publish(
-            { deviceId: deviceId },
-            {
-                notification: {
-                    title: 'Push Tutorial',
-                    body: 'Hello from device ID!'
-                },
-                data: {
-                    foo: 'bar',
-                    baz: 'qux'
-                }
-            }
-        );
-        showStatus('Sent push to device ID: ' + deviceId, 'success');
-    } catch (error) {
-        showStatus('Error sending push to device: ' + error.message, 'error');
-    }
-}
-
-// Send push notification to a specific client ID
-async function sendPushToClient() {
-    try {
-        const clientId = realtimeClient.auth.clientId;
-        await realtimeClient.push.admin.publish(
-            { clientId: clientId },
-            {
-                notification: {
-                    title: 'Push Tutorial',
-                    body: 'Hello from client ID!'
-                },
-                data: {
-                    foo: 'bar',
-                    baz: 'qux'
-                }
-            }
-        );
-        showStatus('Sent push to client ID: ' + clientId, 'success');
-    } catch (error) {
-        showStatus('Error sending push to client: ' + error.message, 'error');
-    }
-}
+  --data '{"foo":"bar"}'
 ```
 </Code>
 
-Sending to a channel is just publishing a message on a channel with a `push` `extras` field:
+### Publish via a channel <a id="step-5-channel"/>
 
-<Code>
-```javascript
-async function sendPushToChannel() {
-    try {
-        const message = {
-            "name": 'example',
-            "data": "Tutorial message with push extras",
-            "extras": {
-                "push": {
-                    "notification": {
-                        "title": "Tutorial Push",
-                        "body": "This is the tutorial push in channel: " + channelName,
-                    },
-                    "data": {
-                        "customKey": "customValue"
-                    }
-                }
-            }
-        };
+Click **Subscribe** in the app, then publish a push notification to the channel using the [Ably CLI](/docs/platform/tools/cli):
 
-        await channel.publish(message);
-        showStatus('Sent push to ' + channelName, 'success');
-    } catch (error) {
-        showStatus('Error sending push to ' + channelName + ' with error: ' + error.message, 'error');
-    }
-}
-```
-</Code>
-
-The `extras.push` object has two parts:
-
-- `notification`: Contains `title` and `body` that are displayed in the browser notification.
-- `data`: Custom key-value pairs that are delivered to your service worker but not displayed directly.
-
-Add the new buttons to your HTML, then add the following to the `<script>` section. Place the button references after the channel name declaration, and the event listeners before the `getStarted()` call:
-
-<Code>
-```html
-<button id="sendPushToDeviceBtn">Send Push to Device</button>
-<button id="sendPushToClientBtn">Send Push to Client</button>
-<button id="sendPushToChannelBtn">Send Push to Channel</button>
+<Code fixed="true">
+```shell
+ably push publish --channel my-first-push-channel \
+  --title "Hello" \
+  --body "World!" \
+  --message '{"name":"greeting","data":"Hello World!"}'
 ```
 </Code>
 
-<Code>
-```javascript
-const sendPushToDeviceBtn = document.getElementById('sendPushToDeviceBtn');
-const sendPushToClientBtn = document.getElementById('sendPushToClientBtn');
-const sendPushToChannelBtn = document.getElementById('sendPushToChannelBtn');
+Here you can see the first push sent to the `deviceId`. And the second one published to the channel together with the realtime message:
 
-sendPushToDeviceBtn.addEventListener('click', sendPushToDevice);
-sendPushToClientBtn.addEventListener('click', sendPushToClient);
-sendPushToChannelBtn.addEventListener('click', sendPushToChannel);
-```
-</Code>
+![Screenshot of the web push tutorial application showing push notifications received](../../../../images/content/screenshots/getting-started/web-push-getting-started-guide.png)
 
-Now you can send push notifications to your device, client, or channel using the buttons in the UI:
+If you click **Unsubscribe**, you will no longer receive push notifications for that channel. Run the same command again and verify that no notification is received.
 
-![Screenshot of the web push tutorial application showing push controls for sending notifications](../../../../images/content/screenshots/getting-started/web-push-getting-started-guide-2.png)
+To see the full list of options for publishing push notifications with the Ably CLI, run `ably push publish --help` or see the [Ably CLI push documentation](/docs/cli/push). To publish push notifications from your own server code instead of the CLI, see [Push notification publishing](https://ably.com/docs/push/publish).
 
 ## Browser compatibility <a id="browser-compatibility"/>