node-gcm

The goal of this project is providing the best and most easily used interface for Firebase Cloud Messaging. (The name gcm comes from the older name for the service, Google Cloud Messaging.)

By April 11, 2019 users must have migrated from GCM to FCM. If you are using this library, we've already got you covered on the server side (since version 0.14.1) --- just update to the most recent version and you are good.

We appreciate all the help we can get! If you want to help out, check out the Guidelines for Contributing section.

If you are developing an open-source project with a broader scope (like a full Firebase suite), we would love for you to use node-gcm internally.

See the official FCM documentation for more information.

We are currently working on version 2.0.0 of the project, and it is available in an early alpha version. Follow PR #238 to see current status.

Installation

$ npm install node-gcm --save

Note: This package requires Node v4.0 and newer.

Requirements

This library provides the server-side implementation of GCM. You need to generate an API Key.

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 = require('node-gcm');

// Set up the sender with your GCM/FCM API key (declare this once for multiple messages)
var sender = new gcm.Sender('YOUR_API_KEY_HERE');

// Prepare a message to be sent
var message = new gcm.Message({
    data: { key1: 'msg1' }
});

// Specify which registration IDs to deliver the message to
var regTokens = ['YOUR_REG_TOKEN_HERE'];

// Actually send the message
sender.send(message, { registrationTokens: regTokens }, function (err, response) {
	if (err) console.error(err);
	else console.log(response);
});

Usage

var gcm = require('node-gcm');

// 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 if your app is in the background."
	}
});

// 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);
});

// Q: I need to remove all "bad" token from my database, how do I do that? 
//    The results-array does not contain any tokens!
// A: The array of tokens used for sending will match the array of results, so you can cross-check them.
sender.send(message, { registrationTokens: registrationTokens }, function (err, response) {  
  var failed_tokens = response.results                           // Array with result for each token we messaged
    .map((res, i) => res.error ? registrationTokens[i] : null)   // If there's any kind of error, 
                                                                 // pick _the token_ from the _other_ array
    .filter(token => token);                                     // Remove all the null values
  console.log('These tokens are no longer ok:', failed_tokens);
});

Recipients

You can send push notifications to various recipient types by providing one of the following recipient keys:

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.

Additional message options

Notification usage

var message = new gcm.Message();

// Add notification payload as key value
message.addNotification('title', 'Alert!!!');
message.addNotification('body', 'Abnormal data access');
message.addNotification('icon', 'ic_launcher');

// as object
message.addNotification({
  title: 'Alert!!!',
  body: 'Abnormal data access',
  icon: 'ic_launcher'
});

Note: Notifications sent using message.addNotification are only displayed when your app is in the background. Consider sending the notification parameters using message.addData and manually building and displaying a notification in your push receiver logic.

Notification payload option table

Notice notification payload defined in GCM Connection Server Reference

Custom HTTP request options

You can provide custom request options such as proxy and timeout for the HTTP request to the GCM API. 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 options
var requestOptions = {
	proxy: 'https://127.0.0.1:8888',
	timeout: 5000
};

// Set up the sender with your API key and request options
var sender = new gcm.Sender('YOUR_API_KEY_HERE', requestOptions);

// Prepare a GCM message...

// Send it to GCM endpoint with modified request options
sender.send(message, { registrationTokens: regTokens }, function (err, response) {
    if(err) console.error(err);
    else     console.log(response);
});

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 a notification object
• Requirement for all 3 notification fields when sending a notification 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 node app.js

Donate

Bitcoin: 13iTQf7tDhrKgibw2Y3U5SyPJa7R8sQmHQ