APNS (iOS)

pingd can send APNS pushes in two ways.

direct: this server sends pushes straight to Apple.
relay: this server forwards pushes to another pingd instance that holds the Apple credentials.

Modes

Mode	When to use
(unset)	Mock provider. Logs push attempts, sends nothing. Default for development.
`direct`	You have your own Apple `.p8` key and want pingd to send to APNS itself.
`relay`	You don't have Apple credentials. Forward pushes to another pingd instance that does.

Direct mode

You'll need:

Apple Developer account with an active App ID
An APNS Authentication Key (.p8 file)
The Key ID and Team ID associated with that key
Your app's Bundle ID

Set the environment:

PINGD_APNS_MODE=direct
PINGD_APNS_KEY_PATH=/secrets/AuthKey_ABCDE12345.p8
PINGD_APNS_KEY_ID=ABCDE12345
PINGD_APNS_TEAM_ID=TEAM12345
PINGD_APNS_BUNDLE_ID=com.example.app
PINGD_APNS_ENV=production    # or "development" for sandbox

Mount the .p8 file into the container:

volumes:
  - ./secrets/AuthKey_ABCDE12345.p8:/secrets/AuthKey_ABCDE12345.p8:ro

Sandbox vs production tokens. APNS dev tokens only work with PINGD_APNS_ENV=development; production tokens need PINGD_APNS_ENV=production. The wrong combination silently fails.

Relay mode

In relay mode, this server forwards APNS push requests to an upstream pingd server. You can use pingd.dev as the upstream push server, or run your own relay with Apple credentials.

PINGD_APNS_MODE=relay
PINGD_APNS_RELAY_BASE_URL=https://pingd.dev
PINGD_APNS_RELAY_TOKEN=<bearer token for the relay>

Registering an iOS device

Get the APNS device token from didRegisterForRemoteNotificationsWithDeviceToken, then:

POST/devices
Authorization: Bearer <user or guest token>

{
  "name": "Vi's iPhone",
  "platform": "ios",
  "pushType": "apns",
  "pushToken": "<hex device token>",
  "deliveryEnabled": true
}

Then subscribe to topics:

POST/devices/:id/subscriptions
Authorization: Bearer <user or guest token>

{ "topicName": "alerts.critical" }

Previous← Web Push NextFCM →