PushizoDocs
Channels

iOS Push (APNs)

The APNs channel — .p8/.p12 credentials, sandbox/production environments, iOS content fields, badge/sound/category, Notification Service Extension and troubleshooting.

iOS push is sent through the Apple Push Notification service (APNs) HTTP/2 API using token-based (.p8) or certificate-based (.p12) credentials. Client side: iOS SDK; setup: iOS quickstart.

Credentials

MethodFieldsNote
APNs key (recommended).p8 file, Key ID, Team ID, Bundle IDA single key works for all apps and both environments; it never expires
Certificate.p12 + password, Bundle IDRenewed yearly; the dashboard warns you as expiry approaches

Environment (environment): sandbox (Xcode build, development profile) or production (TestFlight, App Store). Pushizo also tracks the environment per device: the SDK detects it from embedded.mobileprovision and sends it with the subscription, so devices from both environments can coexist in the same app. The most common error is an environment mismatch (BadDeviceToken).

API: PUT /v1/apps/{app_id}/channels/ios_push { "provider": "apns", "config": { "key_id", "team_id", "bundle_id", "environment", "p8": "-----BEGIN PRIVATE KEY-----…" } } (multipart is supported for file uploads); POST …/validate connects to APNs and verifies the credentials.

Content fields

FieldAPNs equivalent
headings, subtitle, contentsalert.title, alert.subtitle, alert.body
ios_soundsound (file name in the app bundle)
ios_badge_type (None, SetTo, Increase) + ios_badge_countbadge; Increase is applied on the device by the NSE
ios_categorycategory (action buttons)
thread_idthread-id (grouping)
ios_interruption_level (passive, active, time-sensitive, critical)interruption-level; critical requires an entitlement (critical alert)
ios_relevance_scorerelevance-score (0–1)
target_content_identifiertarget-content-id
big_picture, ios_attachmentsAttachment downloaded by the NSE (image, video, audio)
buttonsCategory-based actions (registered by the SDK)
content_available, mutable_contentSilent push (content-available: 1), mutable-content: 1 for the NSE (set automatically when there is an attachment)
collapse_idapns-collapse-id
ttl, priority (5/10)apns-expiration, apns-priority
dataCustom payload (the delivery ID, URL and buttons are also carried under the hs key)

The push payload is validated against the 4 KB limit; exceeding it returns 422 HS_CONTENT_INVALID.

Notification Service Extension

The NSE downloads rich media, applies badge increments, adds action buttons and sends the reached the device (received) event even when the app is closed. The app and the NSE share storage through the same App Group (regional API base URL and queue). Setup: iOS SDK → NSE.

Delivery and feedback

  • APNs responses are processed immediately: 200 → sent; 410 Unregistered / BadDeviceToken → subscription invalid, subscription.invalidated; TooManyRequests/5xx → exponential retry (30 s → 2 h).
  • received comes from the NSE and opened from the SDK click handler; both appear in the Message Tracking timeline and in webhooks (delivery.delivered, delivery.opened).
  • The channel health job validates the credentials against APNs every 6 hours; if they are rejected, the channel becomes invalid and org owners receive an email.

Troubleshooting

Error / symptomCause and fix
BadDeviceTokenEnvironment mismatch (production push to a sandbox build). Check the channel environment and the device environment.
InvalidProviderToken / 403Key ID / Team ID / .p8 do not match; is the key authorized for APNs?
TopicDisallowedWrong Bundle ID, or the key is not authorized for this app.
Notification arrives but no receivedThe NSE is not installed, or there is no attachment to trigger mutable-content; App Group sharing is missing.
Badge does not incrementios_badge_type: "Increase" requires the NSE.
Silent push does not workcontent_available: true and Background Modes → Remote notifications; iOS throttling (battery, frequent sends).

On this page