Node APN

You can define the JSON payload sent to the device using two different approaches:

1. notification.payload: An object that is JSON encoded. When you set properties on notification.aps (via convenience setters), they are merged into this payload just before transmission. If payload already contains an aps property, it is replaced by the aps properties set via the notification object.

2. notification.rawPayload: If provided, this object is encoded and transmitted exactly as-is. Using rawPayload means convenience setters (like .body or .title) will have no effect on the final JSON output.

// Using .payload (merges with aps properties)
let notification = new apn.Notification();
notification.payload = {
  from: "node-apn",
  source: "web",
};
notification.body = "Hello, world!";

// Using .rawPayload (overrides everything, ignores setters)
let notificationRaw = new apn.Notification();
notificationRaw.rawPayload = {
  from: "node-apn",
  source: "web",
  aps: {
    "content-available": 1
  }
};
notificationRaw.body = "Hello, world!"; // This will be ignored in the output

When send, manageChannels, or broadcast promises resolve, they return an object with two properties: sent and failed.

sent

An array of device tokens or bundle identifiers that were successfully accepted by Apple.

failed

An array of objects describing failures. Failures fall into two categories:

1. Rejected Notifications (Status/Reason): Apple rejected the notification (e.g., device is unregistered). The object contains device, status (HTTP code), and response.reason.

{
  device: "834c8b48e6254e47435d74720b1d4a13e3e57d0bf318333c284c1db8ce8ddc58",
  status: 410,
  response: { reason: "Unregistered" }
}

2. Error Notifications (Connection Error): A network or connection-level error occurred. The object contains device and an error property (an Error object).

{
  device: "834c8b48e6254e47435d74720b1d4a13e3e57d0bf318333c284c1db8ce8ddc58",
  error: Error // Details about the connection failure
}

Once you have a Provider and a Notification object, use the provider.send() method to transmit the notification to a list of device tokens.

provider.send(notification, deviceTokens) returns a Promise that resolves when the transmission process is complete. The resolved response object contains two arrays:

• response.sent: An array of device tokens that successfully received the notification.
• response.failed: An array of objects for failed deliveries. Each object contains the device token and either an error or the status and response received from the Apple API.

provider.send(notification, deviceTokens).then( (response) => {
	// response.sent: Array of device tokens to which the notification was sent successfully
	// response.failed: Array of objects containing the device token (`device`) and either an `error`, or a `status` and `response` from the API
});

Live Activity notifications require a specific topic format (<your-app-bundle-id>.push-type.liveactivity) and a pushType of liveactivity. You should also configure properties like relevanceScore, timestamp, staleDate, event, and contentState.

let deviceToken = "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7";
let note = new apn.Notification();

note.topic = "<your-app-bundle-id>.push-type.liveactivity";
note.expiry = Math.floor(Date.now() / 1000) + 3600;
note.pushType = "liveactivity";
note.badge = 3;
note.sound = "ping.aiff";
note.alert = "\uD83D\uDCE7 \u2709 You have a new message";
note.payload = {'messageFrom': 'John Appleseed'};
note.relevanceScore = 75;
note.timestamp = Math.floor(Date.now() / 1000);
note.staleDate = Math.floor(Date.now() / 1000) + (8 * 3600);
note.event = "update";
note.contentState = {};

try {
  const result = await apnProvider.send(note, deviceToken);
} catch (error) {
  // handle error
}

In v2.0, you initialize an apn.Provider with your configuration. When sending a notification, you must set the topic property on the apn.Notification object. The send method returns a Promise that resolves to a response object containing sent and failed arrays.

• response.sent: An array of tokens that were successfully sent.
• response.failed: An array of failure objects. If failure.error exists, it indicates a transport-level error (e.g., network issues). Otherwise, use failure.status (HTTP status code) and failure.response (JSON payload) to handle application-level errors.

function setup() {
  let connection = new apn.Provider(configuration);
}

function sendNotification(user) {
  let note = new apn.Notification();
  note.alert = "Hello " + user.name;
  note.topic = "io.github.node-apn.test"; // topic is required

  connection.send(note, user.token).then((response) => {
    response.sent.forEach((token) => {
      notificationSent(user, token);
    });
    response.failed.forEach((failure) => {
      if (failure.error) {
        // A transport-level error occurred (e.g. network problem)
        notificationError(user, failure.device, failure.error);
      } else {
        // `failure.status` is the HTTP status code
        // `failure.response` is the JSON payload
        notificationFailed(user, failure.device, failure.status, failure.response);
      }
    });
  });
}

Starting in iOS 18/iPadOS 18, you can manage push notification channels using apnProvider.manageChannels(note, bundleId, action).

Actions:

• create: Creates a new channel. Requires note.payload to contain {'message-storage-policy': '1', 'push-type': 'liveactivity'}.
• read: Retrieves a specific channel. Requires note.channelId to be populated.
• readAll: Retrieves all active channel IDs for a bundle.
• delete: Deletes a channel. Requires note.channelId to be populated.

Parameters:

• note: An apn.Notification object containing required payload/channel info.
• bundleId: Your app's bundle identifier.
• action: The management operation to perform.

let bundleId = "com.node.apn";
let note = new apn.Notification();
note.requestId = "0309F412-AA57-46A8-9AC6-B5AECA8C4594";
note.payload = {'message-storage-policy': '1', 'push-type': 'liveactivity'};

try {
  // Create a channel
  const result = await apnProvider.manageChannels(note, bundleId, 'create');
  
  // Or read all channels
  // const result = await apnProvider.manageChannels(note, bundleId, 'readAll');
} catch (error) {
  // handle error
}