live-activity-apn

Send Apple Push Notification service (APNs) requests for:

• Live Activity start/update/end events
• Standard APNs alert pushes

This package is a lightweight TypeScript wrapper around APNs HTTP/2 calls.

Installation

npm install live-activity-apn

Requirements

• Apple Developer account with APNs enabled
• APNs auth key (.p8) with:
  • team_id
  • key_id
  • local key_path to the key file
• App bundle_id
• Device token(s) generated by your iOS app

About the .p8 key (APNs Auth Key)

You generate this from the Apple Developer portal:

1. Go to Apple Developer Certificates, Identifiers & Profiles.
2. Create a new key and enable Apple Push Notifications service (APNs).
3. Download the key file (AuthKey_XXXXXXXXXX.p8) immediately (Apple lets you download it only once).
4. Save it securely on your server and set:
   • key_path -> absolute path to this .p8 file
   • key_id -> the key identifier shown in the portal
   • team_id -> your Apple Developer Team ID

Obtain Live Activity Tokens (iOS)

Use the following ActivityKit snippets in your iOS app to collect the required tokens.

Important token usage:

• The token from pushToStartTokenUpdates can only be used to start a live activity.
• The token from activity.pushTokenUpdates (inside activityUpdates) should be used to update or end that live activity.

Push-to-start token (iOS 17.2+)

if #available(iOS 17.2, *) {
    Task {
        for await tokenData in Activity<NotificationAttributes>.pushToStartTokenUpdates {
            let token = tokenData.map { String(format: "%02x", $0) }.joined()
            print("pushToStart token: \(token)")
            // you can later read this from your plugin and send to server
        }
    }
}

Per-activity update token (iOS 16.1+)

if #available(iOS 16.1, *) {
    Task {
        for await activity in Activity<NotificationAttributes>.activityUpdates {
            for await tokenData in activity.pushTokenUpdates {
                let token = tokenData.map { String(format: "%02x", $0) }.joined()
                print("Update token for activity \(activity.id): \(token)")
            }
        }
    }
}

Obtain Device Token for Normal Notifications

Use this Swift callback to convert the APNs deviceToken into a hex string for standard alert pushes.

Swift

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    print("APNs device token: \(token)")
}

Basic Usage

import LiveActivityClient from "live-activity-apn";

const client = new LiveActivityClient({
  app_id: "com.example.app",
  bundle_id: "com.example.app",
  key_id: "ABCD1234",
  key_path: "/absolute/path/AuthKey_ABCD1234.p8",
  team_id: "TEAM123456"
});

await client.startLiveActivity("DEVICE_TOKEN", {
  content_state: {
    title: "Order placed",
    body: "Preparing your order"
  },
  attributes_type: "NotificationAttributes",
  attributes: {
    id: "order-123"
  }
});

API

new LiveActivityClient(config)

config fields:

• team_id: Apple Team ID
• key_id: APNs key ID
• key_path: filesystem path to .p8 key
• bundle_id: your app bundle identifier
• app_id: app identifier value kept for consumer metadata/use

startLiveActivity(deviceToken, payloadState)

Sends APNs event: "start" payload.

updateLiveActivity(deviceToken, payloadState)

Sends APNs event: "update" payload.

endLiveActivity(deviceToken, payloadState?)

Sends APNs event: "end" payload.

alert(deviceToken, alert)

Sends a standard APNs alert push (apns-push-type: alert).

Payload Notes

• payloadState.content_state should match your ActivityKit model.
• attributes_type and attributes are typically required for start events.
• relevance_score is optional and used in update payloads.

Environment and APNs Host

The APNs host is selected via NODE_ENV:

• production -> https://api.push.apple.com
• any other value -> https://api.sandbox.push.apple.com

Running Local Examples

1. Copy .env.example to .env
2. Fill all required values
3. Run one of:

npm run example:start
npm run example:update
npm run example:end
npm run example:alert

Build

npm run build

The package entrypoint exports from dist/index.js with type definitions.

Contributing

Contributions are welcome. Feel free to open issues for bugs/feature requests and submit pull requests for improvements.