‚̧Neverending Prototype Mode
    Have ideas to improve npm?Join in the discussion! ¬Ľ

    apns2
    TypeScript icon, indicating that this package has built-in type declarations

    9.3.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    APNS2

    npm version Twitter

    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.development.push.apple.com'
      ...
    })

    Requirements

    apns2 requires Node.js v12.14 or later

    Keywords

    none

    Install

    npm i apns2

    DownloadsWeekly Downloads

    645

    Version

    9.3.0

    License

    MIT

    Unpacked Size

    33.1 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar