Package Exports

apns2

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (apns2) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

APNS2

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

Now uses the native http2 module in Node.js v10.16 or later

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

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

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

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

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

let 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 8-6

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

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

Requirements

apns2 requires Node.js v10.16 or later