PushizoDocs
OperationsRunbooks

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 → Channels must be open.
  • Apple: an Apple Developer account, a .p8 file 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_key fields are required).

1. APNs (iOS)

  1. Channels → iOS Push → provider APNs.
  2. Enter the Key ID, Team ID and Bundle ID; choose the environment (sandbox: a build installed via Xcode; production: TestFlight/App Store).
  3. Select the .p8 file (its contents are read in the browser and stored encrypted; it can never be viewed again).
  4. 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.
  5. Error mapping:
    ResultMeaningFix
    InvalidProviderTokenKey ID / Team ID / p8 do not matchCheck that all three come from the same Apple account
    TopicDisallowed / BadTopicThe Bundle ID is not authorized for the keyCheck the Bundle ID and the key's push permission
    NETWORKapi.push.apple.com:443 is unreachableOpen firewall/HTTP2 egress
  6. Real device (Phase 4+): open the app on the device; after SDK registration, find the ios_push record 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)

  1. Channels → Android Push → provider FCM.
  2. Select the service account JSON file or paste its contents. Only project_id and client_email remain visible; private_key is encrypted.
  3. Save and validate. Pushizo obtains an access token via OAuth2 and sends a request to a fake token in validate_only mode; 400 INVALID_ARGUMENT / 404 indicates that the credentials are valid.
  4. Error mapping:
    ResultMeaningFix
    OAUTH_FAILEDprivate_key/client_email invalid or clock skewDownload the JSON again; sync the server clock with NTP
    PERMISSION_DENIEDThe service account has no FCM permissionGrant 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 projectMatch the project with the app's google-services.json
  5. Real device (Phase 4+): open the app, find the android_push record under Subscriptions, and send a test push. UNREGISTERED → the app was uninstalled or the token was refreshed.

3. Web Push

  1. 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 SDK config endpoint.
  2. 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.
  3. 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.

On this page