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
| Method | Fields | Note |
|---|---|---|
| APNs key (recommended) | .p8 file, Key ID, Team ID, Bundle ID | A single key works for all apps and both environments; it never expires |
| Certificate | .p12 + password, Bundle ID | Renewed 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
| Field | APNs equivalent |
|---|---|
headings, subtitle, contents | alert.title, alert.subtitle, alert.body |
ios_sound | sound (file name in the app bundle) |
ios_badge_type (None, SetTo, Increase) + ios_badge_count | badge; Increase is applied on the device by the NSE |
ios_category | category (action buttons) |
thread_id | thread-id (grouping) |
ios_interruption_level (passive, active, time-sensitive, critical) | interruption-level; critical requires an entitlement (critical alert) |
ios_relevance_score | relevance-score (0–1) |
target_content_identifier | target-content-id |
big_picture, ios_attachments | Attachment downloaded by the NSE (image, video, audio) |
buttons | Category-based actions (registered by the SDK) |
content_available, mutable_content | Silent push (content-available: 1), mutable-content: 1 for the NSE (set automatically when there is an attachment) |
collapse_id | apns-collapse-id |
ttl, priority (5/10) | apns-expiration, apns-priority |
data | Custom 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→ subscriptioninvalid,subscription.invalidated;TooManyRequests/5xx→ exponential retry (30 s → 2 h). receivedcomes from the NSE andopenedfrom 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
invalidand org owners receive an email.
Troubleshooting
| Error / symptom | Cause and fix |
|---|---|
BadDeviceToken | Environment mismatch (production push to a sandbox build). Check the channel environment and the device environment. |
InvalidProviderToken / 403 | Key ID / Team ID / .p8 do not match; is the key authorized for APNs? |
TopicDisallowed | Wrong Bundle ID, or the key is not authorized for this app. |
Notification arrives but no received | The NSE is not installed, or there is no attachment to trigger mutable-content; App Group sharing is missing. |
| Badge does not increment | ios_badge_type: "Increase" requires the NSE. |
| Silent push does not work | content_available: true and Background Modes → Remote notifications; iOS throttling (battery, frequent sends). |
Web Push
The VAPID-based browser push channel — setup, browser support, service worker, permission prompts, content fields and troubleshooting.
Android Push (FCM)
The Firebase Cloud Messaging HTTP v1 channel — service account, data-only message model, Android content fields, notification channels, delivery feedback and troubleshooting.