push adapter documentation

Author: or-else

docs/API.md

@@ -556,7 +556,7 @@ _Important!_ As a security measure, the client should not send security credenti
 
 ## Push Notifications
 
-Tinode uses compile-time adapters for handling push notifications. The server comes with [Tinode Push Gateway](), [Google FCM](https://firebase.google.com/docs/cloud-messaging/), and `stdout` adapters. Tinode Push Gateway and Google FCM support Android with [Play Services](https://developers.google.com/android/guides/overview) (may not be supported by some Chinese phones), iOS devices and all major web browsers excluding Safari. The `stdout` adapter does not actually send push notifications. It's mostly useful for debugging, testing and logging. Other types of push notifications such as [TPNS](https://intl.cloud.tencent.com/product/tpns) can be handled by writing appropriate adapters.
+Tinode uses compile-time adapters for handling push notifications. The server comes with [Tinode Push Gateway](../server/push/tnpg/), [Google FCM](https://firebase.google.com/docs/cloud-messaging/), and `stdout` adapters. Tinode Push Gateway and Google FCM support Android with [Play Services](https://developers.google.com/android/guides/overview) (may not be supported by some Chinese phones), iOS devices and all major web browsers excluding Safari. The `stdout` adapter does not actually send push notifications. It's mostly useful for debugging, testing and logging. Other types of push notifications such as [TPNS](https://intl.cloud.tencent.com/product/tpns) can be handled by writing appropriate adapters.
 
 If you are writing a custom plugin, the notification payload is the following:
 ```js
@@ -572,7 +572,7 @@ If you are writing a custom plugin, the notification payload is the following:
 
 ### Tinode Push Gateway
 
-Tinode Push Gateway (TNPG) is a proprietary Tinode service which sends push notifications on behalf of Tinode. It uses Google FCM on the backend and as such supports the same platforms as FCM. The main advantage of using TNPG over FCM is simplicity of configuration: mobile clients do not need to be recompiled, all is needed is a configuration update on a server.
+Tinode Push Gateway (TNPG) is a proprietary Tinode service which sends push notifications on behalf of Tinode. Internally it uses Google FCM and as such supports the same platforms as FCM. The main advantage of using TNPG over FCM is simplicity of configuration: mobile clients do not need to be recompiled, all is needed is a [configuration update](../server/push/tnpg/) on a server.
 
 ### Google FCM
 

docs/faq.md

@@ -22,24 +22,9 @@ Alternatively, you can instruct the docker container to save the logs to a direc
 
 ### Q: How to setup push notifications with Tinode Push Gateway?<br/>
 **A**: Enabling TNPG push notifications requires two steps:
- * register at console.tinode.co and obtain a TNPG token
- * configure server with the token
-
-#### Obtain TNPG token
-1. Register at https://console.tinode.co and create an organization.
-2. Get the TPNG token from the _On premise_ section by following the instructions there.
-
-#### Configuring the server
-
-Update the server config [`tinode.conf`](../server/tinode.conf#L384), section `"push"` -> `"name": "tnpg"`:
-```js
-{
-  "enabled": true,
-  "org": "test", // name of the organization you registered at console.tinode.co
-  "token": "SoMe_LonG.RaNDoM-StRiNg.123" // authentication token obtained from console.tinode.co
-}
-```
-Make sure the `fcm` section is disabled `"enabled": false`.
+ * register at console.tinode.co and obtain a TNPG token.
+ * configure server with the token.
+See detailed instructions [here](../server/push/tnpg/).
 
 
 ### Q: How to setup push notifications with Google FCM?<br/>

server/push/fcm/README.md

@@ -0,0 +1,25 @@
+# FCM push adapter
+
+This adapter sends push notifications to mobile clients and web browsers using [Google FCM](https://firebase.google.com/docs/cloud-messaging/). As of the time of this writing it supports Android with [Play Services](https://developers.google.com/android/guides/overview), iOS devices, and all major web browsers [excluding Safari](https://caniuse.com/#feat=push-api).
+
+This adapter requires you to obtain your own credentials from Goole Firebase. If you want to use iOS and Android mobile apps with your service, they must be recompiled with your credentials obtained from Google. If you do not want to recompile mobile clients, consider using TNPG adapter instead.
+
+
+## Configuring FCM adapter
+
+### Server and TinodeWeb
+
+1. Create a project at https://firebase.google.com/ if you have not done so already.
+2. Follow instructions at https://cloud.google.com/iam/docs/creating-managing-service-account-keys to download the credentials file.
+3. Update the server config [`tinode.conf`](../server/tinode.conf#L255), section `"push"` -> `"name": "fcm"`. Do _ONE_ of the following:
+  * _Either_ enter the path to the downloaded credentials file into `"credentials_file"`.
+  * _OR_ copy the file contents to `"credentials"`.<br/><br/>
+    Remove the other entry. I.e. if you have updated `"credentials_file"`, remove `"credentials"` and vice versa.
+4. Update [TinodeWeb](/tinode/webapp/) config [`firebase-init.js`](https://github.com/tinode/webapp/blob/master/firebase-init.js): update `apiKey`, `messagingSenderId`, `projectId`, `appId`, `messagingVapidKey`. See more info at https://github.com/tinode/webapp/#push_notifications
+
+### iOS and Android
+
+1. If you are using an Android client, add `google-services.json` to [Tindroid](/tinode/tindroid/) by following instructions at https://developers.google.com/android/guides/google-services-plugin and recompile the client. You may also optionally submit it to Google Play Store.
+See more info at https://github.com/tinode/tindroid/#push_notifications
+2. If you are using an iOS client, add `GoogleService-Info.plist` to [Tinodios](/tinode/ios/) by following instructions at https://firebase.google.com/docs/cloud-messaging/ios/client) and recompile the client. You may optionally submit the app to Apple AppStore.
+See more info at https://github.com/tinode/ios/#push_notifications

server/push/stdout/README.md

@@ -0,0 +1,4 @@
+# `stdout` push adapter
+
+This is an adapter which logs push notifications to `STDOUT` where they can be redirected to file or processed by some other service.
+This adapter is primarily intended for debugging and logging.

server/push/tnpg/README.md

@@ -0,0 +1,27 @@
+# TNPG: Push Gateway
+
+This is push notifications adapter which communicates with Tinode Push Gateway (TNPG).
+
+TNPG is a proprietary service intended to simplify deployment of on-premise installations.
+Deploying a Tinode server without TNPG requires [configuring Google FCM](../fcm/) with your own credentials including recompiling mobile clients and releasing them to PlayStore and AppStore under your own accounts which is usually time consuming and relatively complex.
+
+TNPG solves this problem by allowing you to send push notifications on behalf of Tinode. Internally it uses Google FCM and as such supports the same platforms as FCM. The main advantage of using TNPG over FCM is simplicity of configuration: mobile clients do not need to be recompiled, all is needed is a configuration update on the server.
+
+## Configuring TNPG adapter
+
+### Obtain TNPG token
+
+1. Register at https://console.tinode.co and create an organization.
+2. Get the TPNG token from the _On premise_ section by following the instructions there.
+
+### Configuring the server
+
+Update the server config [`tinode.conf`](../server/tinode.conf#L384), section `"push"` -> `"name": "tnpg"`:
+```js
+{
+  "enabled": true,
+  "org": "myorg", // name of the organization you registered at console.tinode.co
+  "token": "SoMe_LonG.RaNDoM-StRiNg.12345" // authentication token obtained from console.tinode.co
+}
+```
+Make sure the `fcm` section is disabled `"enabled": false`.