A Node.js module for interfacing with the Apple Push Notification service. (Apple APNs Overview)

Installation

| Version | |----------------| | node >= 20 |

npm is the preferred installation method:

$ npm install node-apn-flitto --save

Usage

1. Load in the module (ts, js)

Typescript

import apn from 'node-apn-flitto'

Javascript

const apn = require('node-apn-flitto')

2. Connecting

Create a new connection to the Apple Push Notification provider API, passing a dictionary of options to the constructor. You must supply your tokenSpec credentials in the options.

Single client

Config

const options = {
  token: {
    key: 'path/to/APNsAuthKey_XXXXXXXXXX.p8',
    keyId: 'key-id',
    teamId: 'developer-team-id',
  },
  // production: deploy, sandbox: xcode build test
  production: true,
  sandbox: false,
}

Typescript

import { type Provider } from 'node-apn-flitto'

new Provider(options)

Typescript - Nestjs

import { type Provider } from 'node-apn-flitto'

@Module({
  ...
  providers: [
    {
      provide: 'APNs',
      useValue: new Provider(options),
    },
  ],
  ...
})

Javascript

// single client

const apnProvider = new apn.Provider(options)

Multiple client

Config

const options1 = {
  token: {
    key: 'path/to/APNsAuthKey1_XXXXXXXXXX.p8',
    keyId: 'key-id',
    teamId: 'developer-team-id',
  },
  production: true,
  sandbox: false,
  clientCount: 0
}
const options2 = {
  token: {
    key: 'path/to/APNsAuthKey2_XXXXXXXXXX.p8',
    keyId: 'key-id',
    teamId: 'developer-team-id',
  },
  production: true,
  sandbox: false,
  clientCount: 1
}

Typescript

import { type MultiProvider } from 'node-apn-flitto'

new MultiProvider(options)

Typescript - Nestjs

import { type MultiProvider } from 'node-apn-flitto'

providers: [
  ...
  {
    provide: 'APNs1',
    useValue: new MultiProvider(options1),
  },
  { 
    provide: 'APNs2', 
    useValue: new MultiProvider(options2),
  },
  ...

Javascript

const apnProvider1 = new apn.MultiProvider(options1)
const apnProvider2 = new apn.MultiProvider(options2)

Connecting through an HTTP proxy

If you need to connect through an HTTP proxy, you simply need to provide the proxy: { host, port } option when creating the provider. For example:

const options = {
  token: {
    key: 'path/to/APNsAuthKey_XXXXXXXXXX.p8',
    keyId: 'key-id',
    teamId: 'developer-team-id',
  },
  proxy: {
    host: '192.168.XX.XX',
    port: 8080,
  },
  production: false,
  sandbox: false,
}

The provider will first send an HTTP CONNECT request to the specified proxy in order to establish an HTTP tunnel. Once established, it will create a new secure connection to the Apple Push Notification provider API through the tunnel.

3. Sending a notification

To send a notification you will first need a device tokenSpec from your app as a string

const deviceToken = 'a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7'

Create a notification object, configuring it with the relevant parameters (See the notification documentation for more details.)

Javascript & TypeScript

const notification = new apn.Notification()
const body = 'flitto notifiaction'
const subtitle = 'bold text title'

notification.expiry = Math.floor(Date.now() / 1000) + 3600 // Expires 1 hour from now.
notification.badge = 3
notification.sound = 'ping.aiff'
notification.alert = { body, subtitle }
notification.payload = { message: body, title: subtitle }
notification.topic = '<your-app-bundle-id>'

// Send the notification to the API with `send`, which returns a promise.
apnProvider.send(notification, deviceToken).then((result) => {
	// see documentation for an explanation of result
})

Typescript - Nestjs

Single

import { Provider } from 'node-apn-flitto'

@Injectable()
export class PushService {
  constructor(
    @Inject('APNs') private readonly apns: Provider,
  )
  ...
}

Multiple

import { MultiProvider } from 'node-apn-flitto'

@Injectable()
export class PushService {
  constructor(
    @Inject('APNs') private readonly apns: MultiProvider,
  )
  ...
}

You should only create one Provider per-process for each certificate/key pair you have. You do not need to create a new Provider for each notification. If you are only sending notifications to one app then there is no need for more than one Provider.

If you are constantly creating Provider instances in your app, make sure to call Provider.shutdown() when you are done with each provider to release its resources and memory.

4. Response

{
  sent: [
    {
      device: 'a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7'
    }
  ],
  failed: [
    {
      device: 'a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7',
      status: 400,
      response: [
        { reason: 'BadDeviceToken' }
      ]
    }
  ]
}

Contributing

We welcome contribution from everyone in this project. Read CONTRIBUTING.md for detailed contribution guide.

License (MIT)

• node-apn