Runbook: APNs and FCM test sends to a real device
Follow this runbook to verify that channel credentials work with the real providers. In Phase 3 the "validate" endpoint opens a test connection to the provider; sending to a real device is completed with Phase 4 (POST /v1/notifications) and Phase 5…
Follow this runbook to verify that channel credentials work with the real providers. In Phase 3 the "validate" endpoint opens a test connection to the provider; sending to a real device is completed with Phase 4 (POST /v1/notifications) and Phase 5 (SDK). The steps here apply to both phases.
Prerequisites
- An app must be created in the dashboard and
App settings → Channelsmust be open. - Apple: an Apple Developer account, a
.p8file generated via Keys → Create a key → Apple Push Notifications service (APNs), the Key ID (10 characters), the Team ID (10 characters), and the app's Bundle ID. - Google: a Firebase project and a service account JSON downloaded via Project settings → Service accounts → Generate new private key (the
project_id,client_email,private_keyfields are required).
1. APNs (iOS)
- Channels → iOS Push → provider APNs.
- Enter the Key ID, Team ID and Bundle ID; choose the environment (sandbox: a build installed via Xcode; production: TestFlight/App Store).
- Select the
.p8file (its contents are read in the browser and stored encrypted; it can never be viewed again). - Save and validate. Expected result: status Active. Pushizo sends a request with an all-zero device token; if Apple returns
400 BadDeviceToken, the credentials are valid. - Error mapping:
Result Meaning Fix InvalidProviderTokenKey ID / Team ID / p8 do not match Check that all three come from the same Apple account TopicDisallowed/BadTopicThe Bundle ID is not authorized for the key Check the Bundle ID and the key's push permission NETWORKapi.push.apple.com:443is unreachableOpen firewall/HTTP2 egress - Real device (Phase 4+): open the app on the device; after SDK registration, find the
ios_pushrecord on the Subscriptions screen; turn on the Test device toggle and send a test push. If the notification does not arrive, check the provider response on the Message Tracking screen (Unregistered→ the token is stale or the environment is wrong, e.g. a production key with a sandbox build).
2. FCM (Android)
- Channels → Android Push → provider FCM.
- Select the service account JSON file or paste its contents. Only
project_idandclient_emailremain visible;private_keyis encrypted. - Save and validate. Pushizo obtains an access token via OAuth2 and sends a request to a fake token in
validate_onlymode;400 INVALID_ARGUMENT/404indicates that the credentials are valid. - Error mapping:
Result Meaning Fix OAUTH_FAILEDprivate_key/client_email invalid or clock skew Download the JSON again; sync the server clock with NTP PERMISSION_DENIEDThe service account has no FCM permission Grant the account the Firebase Cloud Messaging API Admin role; make sure the FCM API is enabled SENDER_ID_MISMATCH(on send)The device token belongs to another Firebase project Match the project with the app's google-services.json - Real device (Phase 4+): open the app, find the
android_pushrecord under Subscriptions, and send a test push.UNREGISTERED→ the app was uninstalled or the token was refreshed.
3. Web Push
- Channels → Web Push → provider Web Push; enter your
mailto:address and site URL. A VAPID key pair is generated automatically; only the public key is visible, and it is published via the SDKconfigendpoint. - If you already have a VAPID pair (e.g. migrating from another service), enter the public and private values together; if they do not match, the save is rejected.
- Real browser (Phase 5): after the Web SDK asks for permission and registers the subscription, send a test push.
410→ the subscription was revoked;401/403→ the VAPID key does not match the site registration (if the key was renewed, browser subscriptions must be renewed).
4. Simulation mode
If you have no real credentials, you can choose the mock provider for any channel. The mock produces deterministic results based on the token prefix: mock:invalid, mock:transient, mock:rate, mock:auth, mock:fail; all other tokens are treated as successful. Use MOCK_LATENCY_MS to simulate latency.
5. Security notes
- Credentials are stored with envelope encryption (
docs/adr/0008) and cannot be read back from the API/UI; only "uploaded / last validation / last error" is shown. - The validate endpoint is limited to 10 requests per minute.
- For key rotation, see
docs/runbooks/key-rotation.md.
Data export / import
The export/import jobs introduced in Phase 8 run in the worker on the maintenance queue; files are kept in S3-compatible object storage (RustFS locally, S3_* environment variables). Dashboard: Audience → Export / Import. API:…
Migrating from your current platform to Pushizo
Pushizo deliberately preserves the legacy provider's concept model (app, subscription, user/alias, tag, segment, template, journey) and SDK surface (initialize → login → User.addTags → Notifications.requestPermission → Session.sendEvent)…