API Documentation Reference

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
• (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.

• AlertNotification
• BackgroundNotification
• ComplicationNotification
• ControlsNotification
• FileProviderNotification
• LiveActivityNotification
• LocationNotification
• MDMNotification
• PushToTalkNotification
• VoipNotification

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 with which they are compatible. 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.

TokenConnector

/**
 * @TODO
 */

---

CertificateConnector

/**
 * @TODO
 */

---

Select the correct target

Device

/**
 * @TODO
 */

---

BroadcastChannel

/**
 * @TODO
 */

---

Sending the notification

/**
 * @TODO
 */

.send()

/**
 * @TODO
 */

---

Managing Broadcast channels

/**
 * @TODO
 */

createBroadcastChannel

/**
 * @TODO
 */

readChannel

/**
 * @TODO
 */

deleteChannel

/**
 * @TODO
 */

readAllChannels

/**
 * @TODO
 */