Skip to content

API Documentation Reference

Jump to bottom
Alexander Cerutti edited this page Jun 14, 2025 · 30 revisions

The flow of sending a notification is pretty easy:

  • Decide which kind of notification you want to send;
  • Decide which kind of Connector you want to use (token or certificates), based on your will or Apple requirements for the kind of notification (refer to Know when to use push types @ Apple Developer)
  • Device which target you want to use (Device or BroadcastChannel)
  • Send it :shipit:
  • (opt) Analyze the outcome and check receiving

Chosing the kind of notification

This package exposes one function per PushType. Each function has a signature and not all the functions accept the same payload. The payload depends on some constraints defined in the Apple Documentation. The idea is that this package automatically abstracts the mandatory or suggested matters by Apple, by letting developers to focus on the integration of notification rather than on implementation.

All the notifications can be imported from the namespace hapns/notifications/*:

import { VoipNotification } from "hapns/notifications/VoipNotification";

Note

Typescript only

Some notifications modules have a NotificationCustomAppData interface exposed, that can help ensuring the correctness of the payload being sent to the notification. This is called Module Augmentation.

Example:

declare module "hapns/notifications/AlertNotification" {
  export interface NotificationCustomAppData {
      myCustomField: number
  }
}

All the notifications objects accept some data that will have to respect this structure (changed, for readability). Some notifications objects will not accept all of them, so providing them will make them getting, therefore, ignored.

interface NotificationData<NotificationPayload extends object, AppPayload extends object, Priority extends 1 | 5 | 10 = 1 | 5 | 10> {
	expiration?: number;
	collapseID?: string;
	priority?: Priority;
	payload?: NotificationPayload;
	appData?: AppPayload;
}
Field Name Description
expiration apns-expiration header, as timestamp
collapseID apns-collapse-id header
priority apns-priority header. Some notifications push types constraint this to a subset of values.
payload Content of the request body that will be set inside aps object, if the notification supports aps, otherwise other
appData Content of the request body that will be set along with aps object, if the notification support custom application data.

AlertNotification

function AlertNotification(
	appBundleId: string,
	data: NotificationData,
): Notification<AlertNotificationBody>;
Name Value
topic Application or Pass (Apple Wallet) BundleID
data NotificationData

Payload in data for this notification, is an object that contains the fields that applies to this kind of notification (refer to Payload key Reference). All the keys are optional.

Key Optional
alert Yes
badge Yes
sound Yes
threadId Yes
category Yes
mutableContent Yes
targetContentId Yes
interruptionLevel Yes
relevanceScore Yes
filterCriteria Yes

Note

Typescript only

This function applies some constraints: alert can be either an empty object ({}), a string or an object. When it is an {}, badge and sound will not be allowed and an error will be returned. Empty object is allowed in Apple Wallet notification, where a local notification is generated after the update.

Note

Typescript only

This function applies some constraints: alert object can contain several kind of data. However, localization keys are mutually exclusive with the "steady" opposite. E.g. using title AND title-loc-key will return an error. Same is valid for body (with loc-key) and subtitle (subtitle-loc-key).

Example:

import { AlertNotification } from "hapns/notifications/AlertNotification";

const notification = AlertNotification("com.x.y.myapp", {
	priority: 10,
	payload: {
		alert: {
			"title-loc-key": "ALERT_TITLE",
			"title-loc-args": ['Hello', 'hapns']
		}
	},
	appData: {
		myCustomData: 5
	}   
});

BackgroundNotification

function BackgroundNotification(
	appBundleId: string,
	data: NotificationData,
): Notification<AlertNotificationBody>;
Name Value
topic Application or Pass (Apple Wallet) BundleID
data NotificationData

Passing a payload in data is forbidden and will be ignored if provided. This because background notifications can have exclusively the key content-available, which is already provided by this function.

Only appData can be provided.

priority is ignored, as automatically and forcefully set to 5, as per Apple requirements.

Example:

import { BackgroundNotification } from "hapns/notifications/BackgroundNotification";

const notification = BackgroundNotification("com.x.y.myapp", {
	appData: {
		myCustomData: 5
	}   
});

ComplicationNotification

/**
 * @TODO
 */

ControlsNotification

/**
 * @TODO
 */

FileProviderNotification

/**
 * @TODO
 */

LiveActivityNotification

/**
 * @TODO
 */

LocationNotification

/**
 * @TODO
 */

MDMNotification

/**
 * @TODO
 */

PushToTalkNotification

/**
 * @TODO
 */

VoipNotification

/**
 * @TODO
 */

Deciding the Connector

A connect is the core component that handles the network communication. This package exposes two Connectors to support both the way supported by Apple: a TokenConnector and a CertificateConnector. Both are accessible through these namespace:

import { TokenConnector } from "hapns/connectors/token";
import { CertificateConnector } from "hapns/connectors/certificate";

Chose one based on your needs.

Warning

Notifications own an association of the connectors they are compatible with. If such constraint is not respected, an error will be fired while sending the notification.

Each Connector has its own parameters. This allows developers to import only dedicated things. The chosen connector will have to be passes to the broadcasting functions (see Managing Broadcast channels) and to the send() (see Sending the notification) function in order to allow them to perform the HTTP requests.

TokenConnector

export function TokenConnector(details: TokenConnectorData): ConnectorProtocol;

Where TokenConnectorData is an object containing the following contents:

Name Type Description Mandatory
key Uint8Array PKCS 8 file content to be read and used as the private key. YES
keyId string A 10-character string Key ID provided by Apple. YES
teamIdentifier string The team ID of the Apple Developer Account. YES

The token connector handles JWT token creation, caching, regeneration after 58 minutes and the HTTP request performing.

Example:

import { TokenConnector } from "hapns/connectors/token";

const connector = TokenConnector({
	key: new Uint8Array(fs.readFileSync(TOKEN_KEY_PATH)),
	keyId: KEY_ID,
	teamIdentifier: TEAM_ID,
});

CertificateConnector

function CertificateConnector(details: CertificateConnectorData): ConnectorProtocol;

Where CertificateConnectorData is an object containing these properties:

Name Type Description Mandatory
cert Uint8Array Certificate file buffer to be read sent when establishing an HTTP/2 connection to APNs. When sending notifications for Apple Wallet, this should be the certificate used to sign the pass itself. YES
key Uint8Array The private key file buffer for the certificate. When sending notifications for Apple Wallet, this should be the private key used to sign the pass itself. YES
passphrase string The passphrase for the private key. If omitted and the key is encrypted, error ERR_OSSL_BAD_DECRYPT might get thrown. NO

The certificate connector handles sending the HTTP Request by attaching cert and key to the request.

Example:

import { CertificateConnector } from "hapns/connectors/certificate";

const connector = CertificateConnector({
	cert: new Uint8Array(fs.readFileSync("...")),
	key: new Uint8Array(fs.readFileSync("...")),
	passphrase: "123456",
});

Select the correct target

The targets are the notification receivers. You can create a target based on the notification you want to deliver. If you are going to deliver a notification to a device, Device will have to be used. BroadcastChannel, as the name says, represents a channel against which LiveActivity notifications can be delivered.

They are accessible from the following namespaces:

import { Device } from "hapns/targets/device";
import { BroadcastChannel } from "hapns/targets/broadcastchannel";

Device

export function Device(deviceToken: string): NotificationTarget;

It accepts the deviceToken the notifications should get delivered to, as parameter.

BroadcastChannel

function BroadcastChannel(channelId: string, bundleId: string): BroadcastChannel;

It accepts the details that identify a channel, so channelId and bundleId for your application.

Note

You will likely won't need to use BroadcastChannel function directly: creating a broadcast channel through createBroadcastChannel, will return one directly. readAllChannels will return as well an array of channels. You can use these two to deliver a notification, to delete a channel or to retrieve its details.

Sending the notification

Sending the notification is fairly easy, if you found easy the rest of the steps. The package exports one method, where everything was discussed until now, flows together: send(). Using send with a connector, a notification, a target (so, answers the questions: "How", "what" and "who to?"), you'll be able to deliver a notification to clients.

send()

function send(connector: ConnectorProtocol, notification: Notification<object>, target: NotificationTarget, useSandbox?: boolean): Promise<DeliveryResult>;

This function returns a Promise with the details of the notification delivery, so:

Name Type Description
apnsId string The notification id. Right now it is not possible to provide it manually. It will be in the future.
apnsUniqueId string Development (Sandbox) environment identifier that can help checking what happened to a notification in the Push Notification Console

Managing Broadcast channels

You can manage the channels remotely by following the dedicate documentation page @ Apple Developer and the following functions.

All the functions can be exported through the following namespace:

import { createBroadcastChannel } from "hapns/channels/broadcast";

createBroadcastChannel

async function createBroadcastChannel(connector: ConnectorProtocol, settings: BroadcastChannelSettings, useSandbox: boolean = false): Promise<BroadcastChannel>;

Provide a connector and some settings. Provide optionally the useSandbox flag to go on production or use the sandbox environment.

The settings are an object with the following properties:

Name Type Description Mandatory
bundleId string Bundle ID associated with the channel YES
messageStoragePolicy `0 1` (number) How long the message should be kept by APN
apnsRequestId string Request Id to be sent with the request NO

A BroadcastChannel target object will be returned on completion, containing the bundleId you provided and the channelId.

You can use the whole object as a target for notifications and with the other broadcasting methods.

readChannel

/**
 * @TODO
 */

deleteChannel

/**
 * @TODO
 */

readAllChannels

/**
 * @TODO
 */

Clone this wiki locally