Create MESSAGE_TYPES.md

README.md

@@ -45,12 +45,16 @@ Hooks do not work with PhoneGap Build. This means you will have to manually make
 ### Google Play Services
 Your build may fail if you are installing multiple plugins that use Google Play Services.  This is caused by the plugins installing different versions of the Google Play Services library.  This can be resolved by installing [cordova-android-play-services-gradle-release](https://github.com/dpa99c/cordova-android-play-services-gradle-release).
 
-If your build is still failing, you can try installing [cordova-android-firebase-gradle-release](https://github.com/dpa99c/cordova-android-firebase-gradle-release).  For more info, read the following [comment](https://github.com/dpa99c/cordova-plugin-request-location-accuracy/issues/50#issuecomment-390025013) about locking down the specific versions for play services and firebase. It is suggested to use `+` instead of `15.+` to ensure the correct versions are used.
+If your build is still failing, you can try installing [cordova-android-firebase-gradle-release](https://github.com/dpa99c/cordova-android-firebase-gradle-release).  For more info, read the following [comment](https://github.com/dpa99c/cordova-plugin-request-location-accuracy/issues/50#issuecomment-390025013) about locking down the specific versions for Play Services and Firebase. It is suggested to use `+` instead of `15.+` to ensure the correct versions are used.
 
 ## Google Tag Manager
 
 Checkout our [guide](docs/GOOGLE_TAG_MANAGER.md) for info on setting up Google Tag Manager.
 
+## Message Types
+
+Checkout our [guide](docs/MESSAGE_TYPES.md) to better understand the types of messages that Firebase provides and how to use them.
+
 ## Configuring Notifications
 
 Checkout our [guide](docs/NOTIFICATIONS.md) for info on configuring notification icons and colors.

docs/MESSAGE_TYPES.md

@@ -0,0 +1,101 @@
+# Message types
+Firebase allows to use two types of message: notification messages and data messages.
+
+## Notification message
+### Behaviour
+* if the app is closed or in background, displays a notification in the notification tray of the user's device, when the notification is touched, `onNotificationOpen` is called
+* if the app is in foreground, calls immediately `onNotificationOpen`
+### The tap attribute
+To know how the `onNotificationOpen` was called it is possible to check the `tap` attribute, like this:
+```
+window.FirebasePlugin.onNotificationOpen(
+  function(notification) {
+    if(notification.tap) {
+      console.log("Notification touched by the user");
+    }
+    else {
+      console.log("Notification received while in foreground");
+    }
+  }, 
+function(error) {
+    console.error(error);
+});
+```
+### FCM API Call from server via HTTP(s)
+Send request to:
+```
+https://fcm.googleapis.com/fcm/send
+```
+HTTP Method:
+```
+POST
+```
+Additional headers:
+```
+Content-Type: application/json
+Authorization:key=<Your FCM Server API key>
+```
+The request body:
+```
+{
+    "registration_ids" : ["<Your client FCM token>"],
+    "notification" : {
+        "title":"<Your notification title>",
+        "body":"<Your notification body>"
+    }
+}
+```
+Or, the request body if you want to add some custom data payload:
+```
+{
+    "registration_ids" : ["<Your client FCM token>"],
+    "notification" : {
+        "title":"<Your notification title>",
+        "body":"<Your notification body>"
+    }
+    "data" : {
+        "<customKey1>":"<customData1>",
+        "<customKey2>":"<customData2>"
+    }
+}
+```
+## Data message
+### Behaviour
+* if the app is closed or in background, the message is enqueued, the queue will be read when the app will be opened, and `onNotificationOpen` will be called (with `notification.tap`=`false`)
+* if the app is in foreground, calls immidiately `onNotificationOpen` (with `notification.tap`=`false`)
+
+### FCM API Call from server via HTTP(s)
+Send request to:
+```
+https://fcm.googleapis.com/fcm/send
+```
+HTTP Method:
+```
+POST
+```
+Additional headers:
+```
+Content-Type: application/json
+Authorization:key=<Your FCM Server API key>
+```
+The request body, just omit the `notification` section of the body:
+```
+{
+    "registration_ids" : ["<Your client FCM token>"],
+    "data" : {
+        "<customKey1>":"<customData1>",
+        "<customKey2>":"<customData2>"
+    }
+}
+```
+## How to read the custom data from your app
+Supposing you have, in your `data` section `"<customKey1>":"<customData1>"`, to read the `customKey1` value from your app, you can just check the attribute `notification.customKey1`, like this:
+```
+window.FirebasePlugin.onNotificationOpen(
+  function(notification) {
+    console.log(notification.customKey1);
+  }, 
+function(error) {
+    console.error(error);
+});
+```