From 05af39cd6976df3e80a6479d5bde6abf43a8bb16 Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 22 May 2024 02:15:07 +0100
Subject: [PATCH] docs: add README docs for web push

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 348cecd06..34d054ebe 100644
--- a/README.md
+++ b/README.md
@@ -322,6 +322,58 @@ await channel.setOptions({cipher: {key: <key>}});
 // New encryption settings are in effect
 ```
 
+### Push activation
+
+Push activation is supported for browser clients, via the Push plugin. In order to use push activation, you must pass in the plugin via client options.
+
+You also need to provide a path to a service worker which will be registered when the client is activated, and will handle receipt of push notifications.
+
+```javascript
+import * as Ably from 'ably';
+import Push from 'ably/push';
+
+const realtime = new Ably.Realtime({
+    ...options,
+    pushServiceWorkerUrl: '/my_service_worker.js',
+    plugins: { Push }
+});
+```
+
+Example service worker:
+
+```javascript
+// my_service_worker.js
+self.addEventListener("push", async (event) => {
+  const { notification } = await event.data.json();
+  self.registration.showNotification(notification.title, notification);
+});
+```
+
+To register the device to receive push notifications, you must call the `activate` method:
+
+```javascript
+await realtime.push.activate();
+```
+
+Once the client is activated, you can subscribe to recieve push notifcations on a channel:
+
+```javascript
+const channel = realtime.channels.get('my_push_channel');
+
+// Subscribe the device to receive push notifcations for a channel...
+await channel.push.subscribeDevice();
+
+// ...or subscribe all devices associated with the client's cliendId to receive notifcations from the channel
+await channel.push.subscribeClient();
+
+// When you no longer need to be subscribed to push notifcations, you can remove the subscription:
+await channel.push.unsubscribeDevice()
+// Or:
+await channel.push.unsubscribeClient()
+```
+
+For more information on publishing push notifcations over Ably, see the [Ably push documentation](https://ably.com/docs/push).
+
 ### Message interactions
 
 Message Interactions allow you to interact with messages previously sent to a channel. Once a channel is enabled with Message Interactions, messages received by that channel will contain a unique `timeSerial` that can be referenced by later messages.
@@ -503,10 +555,6 @@ You can also view the [community reported Github issues](https://github.com/ably
 
 To see what has changed in recent versions, see the [CHANGELOG](CHANGELOG.md).
 
-## Known Limitations
-
-This library currently does not support being the [target of a push notification](https://www.ably.com/docs/general/push/activate-subscribe) (i.e. web push).
-
 #### Browser-specific issues
 
 - ["Unable to parse request body" error when publishing large messages from old versions of Internet Explorer](https://support.ably.com/solution/articles/3000062360-ably-js-unable-to-parse-request-body-error-when-publishing-large-messages-from-old-browsers).