APNS2

Node client for connecting to Apple's Push Notification Service using the new HTTP/2 protocol with JSON web tokens.

Create Client

Create an APNS client using a signing key:

const APNS = require('apns2');

let client = new APNS({
  team: `TFLP87PW54`,
  keyId: `123ABC456`,
  signingKey: fs.readFileSync(`${__dirname}/path/to/auth.p8`),
  defaultTopic: `com.tablelist.Tablelist`
});

Sending Notifications

Basic

Send a basic notification with message:

const BasicNotification = APNS.BasicNotification;

let bn = new BasicNotification(deviceToken, 'Hello, World');

client.send(bn).then(() => {
  // sent successfully
}).catch(err => {
  console.error(err.reason);
});

Send a basic notification with message and options:

const BasicNotification = APNS.BasicNotification;

let bn = new BasicNotification(deviceToken, 'Hello, World', {
  badge: 4,
  data: {
    userId: user.getUserId
  }
});

client.send(bn).then(() => {
  // sent successfully
}).catch(err => {
  console.error(err.reason);
});

Silent

Send a silent notification using content-available key:

const SilentNotification = APNS.SilentNotification;

let sn = new SilentNotification(deviceToken);

client.send(sn).then(() => {
  // sent successfully
}).catch(err => {
  console.error(err.reason);
});

Note: Apple recommends that no options other than the content-available flag be sent in order for a notification to truly be silent and wake up your app in the background. Therefore this class does not accept any additional options in the constructor.

Advanced

For complete control over the push notification packet use the base Notification class:

const Notification = APNS.Notification;

let notification = new Notification(deviceToken, {
  aps: { ... }
});

client.send(notification).then(() => {
  // sent successfully
}).catch(err => {
  console.error(err.reason);
});

Available options can be found at APNS Payload Options

Error Handling

All errors are defined in ./lib/errors.js and come directly from APNS Table 6-6

You can easily listen for these errors by attaching an error handler to the APNS client:

const errors = APNS.errors;

// Listen for a specific error
client.on(errors.badDeviceToken, err => {
  // Handle accordingly...
  // Perhaps delete token from your database
  console.error(err.reason, err.statusCode, err.notification.deviceToken);
});

// Listen for any error
client.on(errors.error, err => {
  console.error(err.reason, err.statusCode, err.notification.deviceToken);
});

Environments

By default the APNS client connects to the production push notification server. This is identical to passing in the options:

let client = new APNS({
  host: 'api.push.apple.com',
  port: 443,
  ...
});

To connect to the development push notification server, pass the options:

let client = new APNS({
  host: 'api.development.push.apple.com',
  port: 443,
  ...
});

Setup Certificates

After adding a certificate in the developer portal, download the aps.cer file, open it, and add it to your login keychain.

Then find the newly added certificate in Keychain Access, expand it, and right-click the private key to export it. Save it as key.p12.

Move aps.cer and key.p12 to the same directory, perhaps your desktop, and perform the following in that directory:

$ openssl x509 -in aps.cer -inform DER -outform PEM -out cert.pem
$ openssl pkcs12 -in key.p12 -out key.pem -nodes

You can now move the generated cert.pem and key.pem into your application directory so you can pass in the file path to the APNS constructor.

Requirements

apns2 is written entirely in ES2015 and therefore requires Node.js v6 or later. I intended to get this working on Node v4 LTS which also supports the relevant ES2015 features, however, v4 does not support ALPN.