Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AndrewBarba/apns2
Node client for connecting to Apple's Push Notification Service using the new HTTP/2 protocol with JSON web tokens
https://github.com/AndrewBarba/apns2
apns apple http2 ios nodejs promise push-notifications
Last synced: about 2 months ago
JSON representation
Node client for connecting to Apple's Push Notification Service using the new HTTP/2 protocol with JSON web tokens
- Host: GitHub
- URL: https://github.com/AndrewBarba/apns2
- Owner: AndrewBarba
- License: mit
- Created: 2016-06-18T21:29:01.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-05-28T19:59:05.000Z (8 months ago)
- Last Synced: 2024-05-29T10:45:38.403Z (8 months ago)
- Topics: apns, apple, http2, ios, nodejs, promise, push-notifications
- Language: TypeScript
- Size: 381 KB
- Stars: 106
- Watchers: 6
- Forks: 31
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# apns2
[](https://badge.fury.io/js/apns2)
[](http://twitter.com/andrew_barba)
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:
```typescript
import { ApnsClient } from 'apns2'
const client = new ApnsClient({
team: `TFLP87PW54`,
keyId: `123ABC456`,
signingKey: fs.readFileSync(`${__dirname}/path/to/auth.p8`),
defaultTopic: `com.tablelist.Tablelist`,
requestTimeout: 0, // optional, Default: 0 (without timeout)
keepAlive: true, // optional, Default: 5000
})
```
## Sending Notifications
#### Basic
Send a basic notification with message:
```typescript
import { Notification } from 'apns2'
const bn = new Notification(deviceToken, { alert: 'Hello, World' })
try {
await client.send(bn)
} catch (err) {
console.error(err.reason)
}
```
Send a basic notification with message and options:
```typescript
import { Notification } from 'apns2'
const bn = new Notification(deviceToken, {
alert: '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:
```typescript
import { SilentNotification } from 'apns2'
const sn = new SilentNotification(deviceToken)
try {
await client.send(sn)
} catch (err) {
console.error(err.reason)
}
```
Note: [Apple recommends](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app#2980040) 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:
```typescript
import { Notification } from 'apns2'
const notifications = [
new Notification(deviceToken1, { alert: 'Hello, World' }),
new Notification(deviceToken2, { alert: '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:
```typescript
import { Notification } from '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](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification#2943363)
## Error Handling
All errors are defined in `./lib/errors.js` and come directly from [APNS Table 4](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/handling_notification_responses_from_apns#3394535)
You can easily listen for these errors by attaching an error handler to the APNS client:
```typescript
import { Errors } from '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:
```typescript
const client = new ApnsClient({
host: 'api.push.apple.com'
...
})
```
To connect to the development push notification server, pass the options:
```typescript
const client = new ApnsClient({
host: 'api.sandbox.push.apple.com'
...
})
```
## Requirements
`apns2` requires Node.js v16 or later