Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A NodeJS wrapper library port to send data to Android devices via Google Cloud Messaging
JavaScript

Merge pull request #153 from bastienleonard/topic

Support explicit topic target in send()
latest commit 29d92ff9c3
@hypesystem hypesystem authored

README.md

node-gcm

node-gcm is a Node.JS library for Google Cloud Messaging for Android, which replaces Cloud 2 Device Messaging (C2DM).

Installation

$ npm install node-gcm

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

var message = new gcm.Message();

message.addData('key1', 'msg1');

var regIds = ['YOUR_REG_ID_HERE'];

// Set up the sender with you API key
var sender = new gcm.Sender('YOUR_API_KEY_HERE');

// Now the sender can be used to send messages
sender.send(message, { registrationIds: regIds }, function (err, result) {
    if(err) console.error(err);
    else    console.log(result);
});

// Send to a topic, with no retry this time
sender.sendNoRetry(message, { topic: '/topics/global' }, function (err, result) {
    if(err) console.error(err);
    else    console.log(result);
});

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 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 IDs of the devices you want to send to
var registrationIds = [];
registrationIds.push('regId1');
registrationIds.push('regId2');

// Send the message
// ... trying only once
sender.sendNoRetry(message, { registrationIds: registrationIds }, function(err, result) {
  if(err) console.error(err);
  else    console.log(result);
});

// ... or retrying
sender.send(message, { registrationIds: registrationIds }, function (err, result) {
  if(err) console.error(err);
  else    console.log(result);
});

// ... or retrying a specific number of times (10)
sender.send(message, { registrationIds: registrationIds }, 10, function (err, result) {
  if(err) console.error(err);
  else    console.log(result);
});

Notice that you can at most send notifications to 1000 registration ids at a time. This is due to a restriction on the side of the GCM API.

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

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

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

Something went wrong with that request. Please try again.