From fa2434af77763e9534229f65c99b19f47d592f71 Mon Sep 17 00:00:00 2001 From: Simon MacDonald Date: Tue, 3 Jul 2018 16:42:41 -0400 Subject: [PATCH] :memo: Update payload with fcm instead of gcm where appropriate --- docs/PAYLOAD.md | 219 +++++++++++++++++++++++++----------------------- 1 file changed, 114 insertions(+), 105 deletions(-) diff --git a/docs/PAYLOAD.md b/docs/PAYLOAD.md index 239ab4903..6acf4367e 100644 --- a/docs/PAYLOAD.md +++ b/docs/PAYLOAD.md @@ -1,46 +1,46 @@ -* [Overview](#overview) - * [Foreground Events](#push-message-arrives-with-app-in-foreground) - * [Background Events](#push-message-arrives-with-app-in-background) - * [Tap Events](#user-clicks-on-notification-in-notification-center) -* [Push Notification Message Format Overview](#push-notification-message-format-overview) -* [Android Behaviour](#android-behaviour) - * [Notification vs Data Payloads](#notification-vs-data-payloads) - * [Localization](#localization) - * [Images](#images) - * [Sound](#sound) - * [Stacking](#stacking) - * [Inbox Stacking](#inbox-stacking) - * [Action Buttons](#action-buttons) - * [In Line Replies](#in-line-replies) - * [Led in Notifications](#led-in-notifications) - * [Vibration Pattern in Notifications](#vibration-pattern-in-notifications) - * [Priority in Notifications](#priority-in-notifications) - * [Picture Messages](#picture-messages) - * [Background Notifications](#background-notifications) - * [Use of content_available: true](#use-of-content_available-true) - * [Caching](#caching) - * [Chinese Android Phones](#chinese-android-phones) - * [Application force closed](#application-force-closed) - * [Visibility](#visibility-of-notifications) - * [Ongoing Notifications](#ongoing-notifications) - * [Badges](#badges) - * [Support for Twilio Notify](#support-for-twilio-notify) - * [Notification ID](#notification-id) - * [Clicking Notification Does Not Bring App to Foreground](#clicking-notification-does-not-bring-app-to-foreground) - * [Notification Channels](#notification-channels) -* [iOS Behaviour](#ios-behaviour) - * [Sound](#sound-1) - * [Background Notifications](#background-notifications-1) - * [VoIP Notifications](#voip-notifications) - * [Action Buttons](#action-buttons-1) - * [Action Buttons using GCM on iOS](#action-buttons-using-gcm-on-ios) - * [GCM and Additional Data](#gcm-and-additional-data) -* [FCM Payload Details](#fcm-payload-details) -* [Windows Behaviour](#windows-behaviour) - * [Notifications](#notifications) - * [Setting Toast Capable Option for Windows](#setting-toast-capable-option-for-windows) - * [Disabling the default processing of notifications by Windows](#disabling-the-default-processing-of-notifications-by-windows) - * [Background Notifications](#background-notifications-2) +- [Overview](#overview) + - [Foreground Events](#push-message-arrives-with-app-in-foreground) + - [Background Events](#push-message-arrives-with-app-in-background) + - [Tap Events](#user-clicks-on-notification-in-notification-center) +- [Push Notification Message Format Overview](#push-notification-message-format-overview) +- [Android Behaviour](#android-behaviour) + - [Notification vs Data Payloads](#notification-vs-data-payloads) + - [Localization](#localization) + - [Images](#images) + - [Sound](#sound) + - [Stacking](#stacking) + - [Inbox Stacking](#inbox-stacking) + - [Action Buttons](#action-buttons) + - [In Line Replies](#in-line-replies) + - [Led in Notifications](#led-in-notifications) + - [Vibration Pattern in Notifications](#vibration-pattern-in-notifications) + - [Priority in Notifications](#priority-in-notifications) + - [Picture Messages](#picture-messages) + - [Background Notifications](#background-notifications) + - [Use of content_available: true](#use-of-content_available-true) + - [Caching](#caching) + - [Chinese Android Phones](#chinese-android-phones) + - [Application force closed](#application-force-closed) + - [Visibility](#visibility-of-notifications) + - [Ongoing Notifications](#ongoing-notifications) + - [Badges](#badges) + - [Support for Twilio Notify](#support-for-twilio-notify) + - [Notification ID](#notification-id) + - [Clicking Notification Does Not Bring App to Foreground](#clicking-notification-does-not-bring-app-to-foreground) + - [Notification Channels](#notification-channels) +- [iOS Behaviour](#ios-behaviour) + - [Sound](#sound-1) + - [Background Notifications](#background-notifications-1) + - [VoIP Notifications](#voip-notifications) + - [Action Buttons](#action-buttons-1) + - [Action Buttons using FCM on iOS](#action-buttons-using-fcm-on-ios) + - [FCM and Additional Data](#fcm-and-additional-data) +- [FCM Payload Details](#fcm-payload-details) +- [Windows Behaviour](#windows-behaviour) + - [Notifications](#notifications) + - [Setting Toast Capable Option for Windows](#setting-toast-capable-option-for-windows) + - [Disabling the default processing of notifications by Windows](#disabling-the-default-processing-of-notifications-by-windows) + - [Background Notifications](#background-notifications-2) # Overview @@ -50,28 +50,28 @@ The following flowchart attempts to give you a picture of what happens when a pu ## Push message arrives with app in foreground -* The push plugin receives the data from the remote push service and calls all of your `on('notification')` event handlers. -* The message is _not_ displayed in the devices' notification center, as that is not normal behaviour for Android or iOS. +- The push plugin receives the data from the remote push service and calls all of your `on('notification')` event handlers. +- The message is _not_ displayed in the devices' notification center, as that is not normal behaviour for Android or iOS. ## Push message arrives with app in background -* The push plugin receives the data from the remote push service and checks to see if there is a title or message in the received data object. If there is, then the message will be displayed in the devices notification center. -* Then the push plugin checks to see if the app is running. If the user has killed the application, then no further processing of the push data will occur. -* If the app is running in the background the push plugin then checks to see if `content-available` exists in the push data. -* If `content-available` is set to `1`, then the plugin calls all of your `notification` event handlers. +- The push plugin receives the data from the remote push service and checks to see if there is a title or message in the received data object. If there is, then the message will be displayed in the devices notification center. +- Then the push plugin checks to see if the app is running. If the user has killed the application, then no further processing of the push data will occur. +- If the app is running in the background the push plugin then checks to see if `content-available` exists in the push data. +- If `content-available` is set to `1`, then the plugin calls all of your `notification` event handlers. ## User clicks on notification in notification center -* The app starts. -* Then the plugin calls all of your `notification` event handlers. +- The app starts. +- Then the plugin calls all of your `notification` event handlers. > Note: if the push payload contained `content-available: 1` then your `notification` event handler has already been called. It is up to you to handle the double event. Some ways to handle this _double_ event are: -* don't include title/message in the push so it doesn't show up in the shader. -* send two pushes, one to be processed in the background, and the other to show up in the shade. -* include a unique ID in your push so you can check to see if you've already processed this event. +- don't include title/message in the push so it doesn't show up in the shader. +- send two pushes, one to be processed in the background, and the other to show up in the shade. +- include a unique ID in your push so you can check to see if you've already processed this event. # Push Notification Message Format Overview @@ -365,14 +365,14 @@ With Android now greatly using Material design since 5.0 (Lollipop), push notifi You should design one with these guidelines in mind: -* 96x96 pixels -* Transparent background -* White foreground +- 96x96 pixels +- Transparent background +- White foreground For more details, please read: -* https://material.io/tools/icons -* https://material.io/design/iconography/ +- https://material.io/tools/icons +- https://material.io/design/iconography/ **Note:** any color foreground will work - any non-transparent pixels are just rendered white. @@ -407,7 +407,7 @@ Please follow the [Android icon design guidelines](https://www.google.com/design Additionally, each push can include a large icon which is used to personalize each push. The location of the image may be one of three types. -The first is the `res/drawable` folder in your app. This JSON is sent from GCM: +The first is the `res/drawable` folder in your app. This JSON is sent from FCM: ```javascript { @@ -452,7 +452,7 @@ Would look for the _twitter_ image in the `res/drawable` folder and produce the ![2015-07-24 02 34 41](https://cloud.githubusercontent.com/assets/353180/8866903/2df48028-3190-11e5-8176-fe8b3f7c5aab.png) -The second is the _assets_ folder in your app. This JSON sent from GCM: +The second is the _assets_ folder in your app. This JSON sent from FCM: ```javascript { @@ -497,7 +497,7 @@ Would look for the _logo.png_ file in the assets/www/img folder. Since your apps ![2015-07-24 02 20 02](https://cloud.githubusercontent.com/assets/353180/8866901/2df19052-3190-11e5-8c16-a355c59209f3.png) -The third is the remote _URL_. This JSON sent from GCM: +The third is the remote _URL_. This JSON sent from FCM: ```javascript { @@ -542,7 +542,7 @@ Produces the following notification. ![2015-07-24 02 17 55](https://cloud.githubusercontent.com/assets/353180/8866900/2df0ab06-3190-11e5-9a81-fdb85bb0f5a4.png) -Finally, the Material UI guidelines recommend using a circular icon for the large icon if the subject of the image is a person. This JSON sent from GCM: +Finally, the Material UI guidelines recommend using a circular icon for the large icon if the subject of the image is a person. This JSON sent from FCM: ```javascript { @@ -556,25 +556,33 @@ Finally, the Material UI guidelines recommend using a circular icon for the larg } ``` -Here is an example using node-gcm that sends the above JSON: +Here is an example using fcm-node that sends the above JSON: -```javascript -const gcm = require('node-gcm'); +````javascript +const FCM = require('fcm-node'); // Replace these with your own values. const apiKey = 'replace with API key'; const deviceID = 'my device id'; -const service = new gcm.Sender(apiKey); -const message = new gcm.Message(); -message.addData('title', 'Large Circular Icon'); -message.addData('message', 'Loaded from URL'); -message.addData( - 'image', - 'https://pbs.twimg.com/profile_images/837060031895896065/VHIQ4oUf_400x400.jpg' -); -message.addData('image-type', 'circular'); -service.send(message, { registrationTokens: [deviceID] }, (err, response) => { - if (err) console.error(err); - else console.log(response); +const fcm = new FCM(apiKey); + +const message = { + to: deviceID, + data: { + title: 'Large Circular Icon', + message: 'Loaded from URL', + image: + 'https://pbs.twimg.com/profile_images/837060031895896065/VHIQ4oUf_400x400.jpg', + 'image-type': 'circular' + } +}; + +fcm.send(message, (err, response) => { + if (err) { + console.log(err); + console.log('Something has gone wrong!'); + } else { + console.log('Successfully sent with response: ', response); + } }); ``` @@ -595,7 +603,7 @@ For Android there are three special values for sound you can use. The first is ` "soundname": "default" } } -``` +```` Then second is `ringtone` which will play the phones default ringtone sound. @@ -623,7 +631,7 @@ The third is the empty string which will cause for the playing of sound to be sk } ``` -In order for your your notification to play a custom sound you will need to add the files to your Android project's `res/raw` directory. Then send the follow JSON from GCM: +In order for your your notification to play a custom sound you will need to add the files to your Android project's `res/raw` directory. Then send the follow JSON from FCM: ```javascript { @@ -834,7 +842,7 @@ You will see both "Push number 1" and "Push number 2" in the shade. ## Inbox Stacking -A better alternative to stacking your notifications is to use the inbox style to have up to 8 lines of notification text in a single notification. If you send the following JSON from GCM you will see: +A better alternative to stacking your notifications is to use the inbox style to have up to 8 lines of notification text in a single notification. If you send the following JSON from FCM you will see: ```javascript { @@ -928,7 +936,7 @@ You will get an inbox view so you can display multiple notifications in a single ![2015-08-25 14 01 35](https://cloud.githubusercontent.com/assets/353180/9468727/2d658bee-4b11-11e5-90fa-248d54c8f3f6.png) -If you use `%n%` in the `summaryText` of the JSON coming down from GCM it will be replaced by the number of messages that are currently in the queue. +If you use `%n%` in the `summaryText` of the JSON coming down from FCM it will be replaced by the number of messages that are currently in the queue. ## Action Buttons @@ -949,7 +957,7 @@ push.on('snooze', data => { }); ``` -If you wish to include an icon along with the button name, they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from GCM: +If you wish to include an icon along with the button name, they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from FCM: ```javascript { @@ -1012,7 +1020,7 @@ If your user clicks on the main body of the notification, then your app will be Android N introduces a new capability for push notifications, the in line reply text field. If you wish to get some text data from the user when the action button is called send the following type of payload. -Your notification can include action buttons. If you wish to include an icon along with the button name they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from GCM: +Your notification can include action buttons. If you wish to include an icon along with the button name they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from FCM: ```javascript { @@ -1246,11 +1254,11 @@ fcm.send(message, (err, response) => { }); ``` -Do not confuse this with the GCM option of setting the [delivery priority of the message](https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message). Which is used by GCM to tell the device whether or not it should wake up to deal with the message. +Do not confuse this with the FCM option of setting the [delivery priority of the message](https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message). Which is used by FCM to tell the device whether or not it should wake up to deal with the message. ## Picture Messages -Perhaps you want to include a large picture in the notification that you are sending to your users. Luckily you can do that too by sending the following JSON from GCM. +Perhaps you want to include a large picture in the notification that you are sending to your users. Luckily you can do that too by sending the following JSON from FCM. ```javascript { @@ -1305,7 +1313,7 @@ This will produce the following notification in your tray: On Android if you want your `on('notification')` event handler to be called when your app is in the background it is relatively simple. -First the JSON you send from GCM will need to include `"content-available": "1"`. This will tell the push plugin to call your `on('notification')` event handler no matter what other data is in the push notification. +First the JSON you send from FCM will need to include `"content-available": "1"`. This will tell the push plugin to call your `on('notification')` event handler no matter what other data is in the push notification. ```json { @@ -1391,7 +1399,7 @@ If you do not want this type of behaviour, just omit `"content-available": 1` fr ### Use of content_available: true -The [GCM docs](https://developers.google.com/cloud-messaging/http-server-ref#downstream-http-messages-json) will tell you to send a data payload of: +The FCM docs will tell you to send a data payload of: ```javascript { @@ -1427,9 +1435,9 @@ Instead move `content_available: true` into the `data` object of the payload. Th These phones have a particular quirk that when the app is force closed that you will no longer be able to receive notifications until the app is restarted. In order for you to receive background notifications: -* On your Huawei device go to Settings > Protected apps > check "My App" where. -* On your Xiaomi make sure your phone has the "Auto-start" property enabled for your app. -* On your Asus make sure your phone has the "Auto-start" property enabled for your app. +- On your Huawei device go to Settings > Protected apps > check "My App" where. +- On your Xiaomi make sure your phone has the "Auto-start" property enabled for your app. +- On your Asus make sure your phone has the "Auto-start" property enabled for your app. More explicit instructions can be read on [Forbes website](https://www.forbes.com/sites/bensin/2017/07/28/how-to-fix-push-notifications-on-oppo-phones/#72a523371735). @@ -1656,9 +1664,9 @@ fcm.send(message, (err, response) => { This plugin seamlessly supports payloads generated by Twilio Notify on Android. Specifically the parameters passed in to the Twilio REST API are available in the message payload passed to your app as follows: -* `Title` --> `data.title` -* `Body` --> `data.message` -* `Sound` --> `data.sound` +- `Title` --> `data.title` +- `Body` --> `data.message` +- `Sound` --> `data.sound` Here is an example request to Twilio REST API and the corresponding JSON received by your app. @@ -1948,9 +1956,9 @@ This will produce the following notification in your tray: If your users clicks on the main body of the notification your app will be opened. However, if they click on either of the action buttons the app will open (or start) and the specified JavaScript callback will be executed. -### Action Buttons using GCM on iOS +### Action Buttons using FCM on iOS -If you are using GCM to send push messages on iOS you will need to send a different payload in order for the action buttons to be present in the notification shade. You'll need to use the `click-action` property in order to specify the category. +If you are using FCM to send push messages on iOS you will need to send a different payload in order for the action buttons to be present in the notification shade. You'll need to use the `click-action` property in order to specify the category. ```javascript { @@ -1963,9 +1971,9 @@ If you are using GCM to send push messages on iOS you will need to send a differ } ``` -## GCM and Additional Data +## FCM and Additional Data -GCM on iOS is a different animal. The way you send data via GCM on Android is like: +FCM on iOS is a different animal. The way you send data via FCM on Android is like: ```javascript { @@ -1992,7 +2000,7 @@ will produce a `notification` event with the following data: } ``` -but in order for the same `notification` event you would need to send your push to GCM iOS in a slight different format: +but in order for the same `notification` event you would need to send your push to FCM iOS in a slight different format: ```javascript { @@ -2010,9 +2018,9 @@ but in order for the same `notification` event you would need to send your push The `title` and `body` need to be in the `notification` part of the payload in order for the OS to pick them up correctly. Everything else should be in the `data` part of the payload. -## GCM Messages Not Arriving +## FCM Messages Not Arriving -For some users of the plugin they are unable to get messages sent via GCM to show up on their devices. If you are running into this issue try setting the `priority` of the message to `high` in the payload. +For some users of the plugin they are unable to get messages sent via FCM to show up on their devices. If you are running into this issue try setting the `priority` of the message to `high` in the payload. ```javascript { @@ -2029,7 +2037,7 @@ For some users of the plugin they are unable to get messages sent via GCM to sho Here's a sample JSON payload to send a push notification to an Android or iOS device using the FCM app server protocol: -```php +```javascript { "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", /* To send a silent push, omit the entire notification section and send only data */ @@ -2043,7 +2051,7 @@ Here's a sample JSON payload to send a push notification to an Android or iOS de "color": "#AABBCC" /* Android: Icon's background color in #RRGGBB format */ }, /* Optional payload that will be available from data.additionalData */ - "data": { + "data": { "custom_var_1": "custom value here", /* Retrieved on app as data.additionalData.custom_var_1 */ "custom_var_2:" "custom value here" /* Retrieved on app as data.additionalData.custom_var_2 */ } @@ -2051,8 +2059,9 @@ Here's a sample JSON payload to send a push notification to an Android or iOS de ``` More information on how to send push notifications using the FCM HTTP protocol and payload details can be found here: -- [Send messages using the legacy app server protocols](https://firebase.google.com/docs/cloud-messaging/send-message#send_messages_using_the_legacy_app_server_protocols "Send messages using the legacy app server protocols") -- [Firebase Cloud Messaging HTTP Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref "Firebase Cloud Messaging HTTP Protocol") + +- [Send messages using the legacy app server protocols](https://firebase.google.com/docs/cloud-messaging/send-message#send_messages_using_the_legacy_app_server_protocols 'Send messages using the legacy app server protocols') +- [Firebase Cloud Messaging HTTP Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref 'Firebase Cloud Messaging HTTP Protocol') # Windows Behaviour