node-gcm-iid
This repo was created for publishing and maintaing the instance ID features of GCM(topic refers to a gcm topic):
- Add single user to a topic
- Add multiple users to a topic
- Remove user(s) from a topic
- Info of a user : app name,connection type, last connect date etc
- List of topics subscribed by the user
I have pushed the additional code to the node-gcm branch so untill they are merged I will be using this repo to deploy code and maitain the npm package.
clone from node-gcm and its info node-gcm is a Node.JS library for Google Cloud Messaging.
Installation
$ npm install node-gcm-iid
Requirements
This library provides the server-side implementation of GCM. You need to generate an API key (Sender ID).
GCM notifications can be sent to both Android and iOS. If you are new to GCM you should probably look into the documentation.
Example application
According to below Usage reference, we could create such application:
var gcm = ; var message = ; message; var regTokens = 'YOUR_REG_TOKEN_HERE'; // Set up the sender with you API keyvar sender = 'YOUR_API_KEY_HERE'; // Now the sender can be used to send messagessender; // Send to a topic, with no retry this timesender; // Set up the Instance ID with you API keyvar instanceId = 'YOUR_API_KEY_HERE'; // Subscribe a user token to a topic, 'TOPIC_NAME' e.g. 'music'instanceId;// Subscribe multiple user tokens to a topicinstanceId;// UnSubscribe multiple user tokens from a topicinstanceId;// See info from a user using his token, details can be true or falseinstanceId;
// See list of topics subscribed by a user using his token instanceId.listTopics(SUBSCRIBER_TOKEN, function (err, response) { if(err) console.error(err); else console.log(response); });
## Usage
```js
var gcm = require('node-gcm-iid');
// Create a message
// ... with default values
var message = new gcm.Message();
// ... or some given values
var message = new gcm.Message({
collapseKey: 'demo',
priority: 'high',
contentAvailable: true,
delayWhileIdle: true,
timeToLive: 3,
restrictedPackageName: "somePackageName",
dryRun: true,
data: {
key1: 'message1',
key2: 'message2'
},
notification: {
title: "Hello, World",
icon: "ic_launcher",
body: "This is a notification that will be displayed ASAP."
}
});
// Change the message data
// ... as key-value
message.addData('key1','message1');
message.addData('key2','message2');
// ... or as a data object (overwrites previous data object)
message.addData({
key1: 'message1',
key2: 'message2'
});
// Set up the sender with you API key
var sender = new gcm.Sender('insert Google Server API Key here');
// Add the registration tokens of the devices you want to send to
var registrationTokens = [];
registrationTokens.push('regToken1');
registrationTokens.push('regToken2');
// Send the message
// ... trying only once
sender.sendNoRetry(message, { registrationTokens: registrationTokens }, function(err, response) {
if(err) console.error(err);
else console.log(response);
});
// ... or retrying
sender.send(message, { registrationTokens: registrationTokens }, function (err, response) {
if(err) console.error(err);
else console.log(response);
});
// ... or retrying a specific number of times (10)
sender.send(message, { registrationTokens: registrationTokens }, 10, function (err, response) {
if(err) console.error(err);
else console.log(response);
});
Recipients
You can send push notifications to various recipient types by providing one of the following recipient keys:
Key | Type | Description |
---|---|---|
to | String | A single registration token, notification key, or topic. |
topic | String | A single publish/subscribe topic. |
notificationKey | String | Deprecated. A key that groups multiple registration tokens linked to the same user. |
registrationIds | String[] | Deprecated. Use registrationTokens instead. |
registrationTokens | String[] | A list of registration tokens. Must contain at least 1 and at most 1000 registration tokens. |
If you provide an incorrect recipient key or object type, an Error
object will be returned to your callback.
Notice that you can at most send notifications to 1000 registration tokens at a time. This is due to a restriction on the side of the GCM API.
Notification usage
var message = ; // Add notification payload as key valuemessage;message;message; // as objectmessage;
Notification payload option table
Parameter | Platform | Usage | Description |
---|---|---|---|
title | Android, iOS (Watch) | Required (Android), Optional (iOS), string | Indicates notification title. This field is not visible on iOS phones and tablets. |
body | Android, iOS | Optional, string | Indicates notification body text. |
icon | Android | Required, string | Indicates notification icon. On Android: sets value to myicon for drawable resource myicon.png. |
sound | Android, iOS | Optional, string | Indicates sound to be played. Supports only default currently. |
badge | iOS | Optional, string | Indicates the badge on client app home icon. |
tag | Android | Optional, string | Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center. |
color | Android | Optional, string | Indicates color of the icon, expressed in #rrggbb format |
click_action | Android, iOS | Optional, string | The action associated with a user click on the notification. On Android, if this is set, an activity with a matching intent filter is launched when user clicks the notification. For example, if one of your Activities includes the intent filter: (Appendix:1)Set click_action to OPEN_ACTIVITY_1 to open it. If set, corresponds to category in APNS payload. |
body_loc_key | iOS | Optional, string | Indicates the key to the body string for localization. On iOS, this corresponds to "loc-key" in APNS payload. |
body_loc_args | iOS | Optional, JSON array as string | Indicates the string value to replace format specifiers in body string for localization. On iOS, this corresponds to "loc-args" in APNS payload. |
title_loc_args | iOS | Optional, JSON array as string | Indicates the string value to replace format specifiers in title string for localization. On iOS, this corresponds to "title-loc-args" in APNS payload. |
title_loc_key | iOS | Optional, string | Indicates the key to the title string for localization. On iOS, this corresponds to "title-loc-key" in APNS payload. |
Notice notification payload defined in GCM Connection Server Reference
Custom GCM request options
You can provide custom request
options such as proxy
and timeout
for the GCM request. For more information, refer to the complete list of request options. Note that the following options cannot be overriden: method
, uri
, body
, as well as the following headers: Authorization
, Content-Type
, and Content-Length
.
// Set custom request optionsvar requestOptions = proxy: 'http://127.0.0.1:8888' timeout: 5000; // Set up the sender with your API key and request optionsvar sender = 'YOUR_API_KEY_HERE' requestOptions; // Prepare a GCM message... // Send it to GCM endpoint with modified request optionssender;
GCM client compatibility
As of January 9th, 2016, there are a few known compatibility issues with 3rd-party GCM client libraries:
phonegap-plugin-push
- No support for subscribing to PubSub topics
- Requirement for
data
payload object when sending anotification
object - Requirement for all 3
notification
fields when sending anotification
object (title, icon, message)
These issues are out of this project's context and can only be fixed by the respective 3rd-party project maintainers.
Debug
To enable debug mode (print requests and responses to and from GCM),
set the DEBUG
environment flag when running your app (assuming you use node app.js
to run your app):
DEBUG=node-gcm-iid node app.js
Donate
Bitcoin: 13iTQf7tDhrKgibw2Y3U5SyPJa7R8sQmHQ