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

const 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 } = require('apns2')

const bn = new BasicNotification(deviceToken, 'Hello, World')

try {
  await client.send(bn)
} catch (err) {
  console.error(err.reason)
}

Send a basic notification with message and options:

const { BasicNotification } = require('apns2')

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

try {
  await client.send(bn)
} catch (err) {
  console.error(err.reason)
}

Silent

Send a silent notification using content-available key:

const { SilentNotification } = require('apns2')

const sn = new SilentNotification(deviceToken)

try {
  await client.send(sn)
} 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.

Many

Send multiple notifications concurrently:

const { BasicNotification } = require('apns2')

const notifications = [
  new BasicNotification(deviceToken1, 'Hello, World'),
  new BasicNotification(deviceToken2, 'Hello, World')
]

try {
  await client.sendMany(notifications)
} catch (err) {
  console.error(err.reason)
}

Advanced

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

const { Notification } = require('apns2')

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

try {
  await client.send(notification)
} 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 4

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

const { Errors } = require('apns2')

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

Close Connections

If you need to close connections to Apple's APNS servers in order to allow the Node process to exit, you can tear down the APNS client:

await client.close()

Once a client is closed you will not be able to use it again. Instead you should instantiate a new client with new APNS().

Environments

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

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

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

const client = new APNS({
  host: 'api.sandbox.push.apple.com'
  ...
})

Requirements

apns2 requires Node.js v12.14 or later