node2dm-lib

node2dm

node2dm

A node.js server for sending push notifications to Google's C2DM push notification server. Written by Instagram to support their Android application, and inspired by statsd's protocol. Check out the original project for more info.

node2dm-lib

We've stripped the server part and encapsulated the C2DM client code into something you can easily integrate into any node.js application. It's CommonJS and mob friendly.

Usage

Install via npm:

npm install node2dm-lib

Configure a client:

var C2DMClient = require('node2dm-lib');

// provide your config to the client constructor.
var client = new C2DMClient ({
    username : "account",
    password : "password",
    source   : "package",

    // if you want to override `util` as the logger,
    // provide an object with a log(str) method as `logger` on the config object.
    logger   : console
});

Pushing a message

Provide all arguments as strings.

client.notifyDevice(registration_id, collapse_key, payload);

Rate limits / errors

Unchanged in node2dm-lib:

node2dm handles a variety of errors that may be passed back from the C2DM service:

• 401: Will force a re-authentication with the C2DM service

• 503: Will back off, respecting the Retry-After header
• QuotaExceeded: In this case, your application has exceeded Google's quota for pushes for the day. node2dm will write out a quota.lock file and quit itself
• DeviceQuotaExceeded: You're sending too many pushes to this device; node2dm will blacklist this token for an hour before trying to send any more messages
• InvalidRegistration/NotRegistered: Something's wrong with this device token; node2dm will drop the message
• MessageTooBig: node2dm will drop this message

Bad token callbacks

Unchanged in node2dm-lib:

node2dm supports a simple webhook-like callback on a bad token error from Google. To set it up, configure serverCallbackHost / serverCallbackPort / serverCallbackPath / serverCallbackSharedSecret in your config object, and you should start receive POST requests with this payload:

device_token (the offending device token)
message_body (the body of the message that was being attempted; can be useful if you need to match something back up on your end)
shared_secret (the serverCallbackSharedSecret, can match up on your end to make sure it's the right server sending you a ping)

Getting stats

node2dm-lib provides node2dm's stats via a client method:

// The method is synchronous:
var stats = client.stats();

// Async-style calls are also supported, to accomodate node-mob mostly,
// but keep in mind that the callback will fire synchronously.
client.stats(function(err, stats) {
    console.log(stats);
});

stats will be something similar to this:

{ "uptime" : 226 // seconds
, "messages_sent" : 20583
, "messages_in_queue" : 0
, "backing_off" : false
, "total_errors" : 9
, "rate_limited_tokens" : 0
, "logged_in_to_c2dm" : true
, "token_age" : 221 }

Contributing

You might want to contribute upstream, we're using this internally so changes should surface here soon enough, unless of course you're fixing a problem we've introduced. The original project is BSD-licensed.