Skip to content

flitto/node-apn

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

node-apn · Flitto

npm version

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

Table of Contents
  1. Installation
  2. Usage
  3. Contributing
  4. License

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)

About

📲 Apple Push Notification module for Node.js

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%