docs: add README docs for web push

README.md

@@ -322,6 +322,57 @@ 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', (event) => {
+  self.showNofication(event.title, event);
+});
+```
+
+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 +554,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).