iOS push notifications with APNs

How it works

When the user agrees to receive notifications, iOS gives the app a device token: the address of that app on that device. The sender posts the notification to APNs with that token and a credential from your Apple account. Apple delivers it to the device.

What you need

• An Apple Developer Program membership.
• The Push Notifications capability turned on for the app in Xcode.
• An APNs authentication key (an AuthKey_XXXX.p8 file), created under Certificates, Identifiers & Profiles → Keys.
• Your account's Team ID, the key's Key ID and the app's Bundle ID.

Connecting APNs to vivapush

In the vivapush dashboard, open the app's credentials, upload the .p8 file and enter the Team ID, Key ID and Bundle ID. vivapush opens an authenticated connection to APNs to check them and shows the result.

vivapush uses token-based authentication (.p8), not .p12 certificates. A .p8 key does not expire every year and works for every app on your Apple team. The file is encrypted and never shown in full.

If the Bundle ID is wrong, Apple rejects every token. vivapush treats that as a configuration error and marks the credential invalid, instead of dropping your devices.

Sandbox and production

Apple runs two environments. Apps installed straight from Xcode use the sandbox; TestFlight and the App Store use production. A token from one environment does not work in the other.

In vivapush, the credential has a default environment and each device can state its own with "apns_environment" when it registers. That way test and production devices live in the same app.

Registering the device

vivapush has no native iOS SDK. The app asks for permission with UNUserNotificationCenter, calls registerForRemoteNotifications and sends the token to the public API with the app's public key (it starts with vp_pub_), which can only register devices.

POST /api/v1/devices
X-VivaPush-App-Key: vp_pub_...

{
  "installation_id": "inst-123456",
  "platform": "ios",
  "token": "APNs token in hexadecimal",
  "apns_environment": "production",
  "external_user_id": "customer-42",
  "language": "en", "country": "US", "timezone": "America/New_York",
  "push_opt_in": true
}

Registration is idempotent per installation_id: a new token replaces the previous one for that installation. When the app opens, call POST /api/v1/devices/activity so the user counts as active for the month.

Images, links and priority

When a notification has an image, vivapush sends mutable-content and the image address in vp_image. To show the image, the app needs a Notification Service Extension that downloads and attaches the file.

On tap, the app receives vp_url (a web or in-app link) and vp_nid, the notification ID. The whole payload must fit in 4 KB, Apple's limit; vivapush does not send notifications larger than that.

High priority delivers right away and is meant for urgent alerts. Normal lets iOS pick the best moment to save battery.

Confirming delivery and opens

When the notification arrives (for example, in the Notification Service Extension) or is opened, call POST /api/v1/events with the vp_nid and the type ("delivered", "opened" or "clicked"). Without that confirmation, vivapush shows only “accepted for delivery”, meaning Apple took the message.

When Apple reports that a token is no longer valid (the app was uninstalled, for example), the device is marked as no longer receiving and the subscriptions.invalidated webhook tells your system.

Frequently asked questions