Skip to Content
DocsAdmin GuideMobile Push Setup

Mobile Push Setup

The Quazzar mobile app (Phase В.4) talks to your OS over a paired relay tunnel. Push notifications arrive on the phone via FCM (Android) or APNs (iOS) and are fanned out from the Control Panel, not from the OS — only CP holds your push credentials.

This page walks an operator through provisioning the FCM service account and APNs key, then wiring them into CP via env vars.

Prerequisites

  • A registered Apple Developer account (for APNs).
  • A Firebase project (for FCM).
  • The Quazzar Control Panel deployment with shell access to set env vars.

1. Firebase Cloud Messaging (Android)

  1. Open the Firebase console .
  2. Create or select a project.
  3. Project settings → Service accounts → Generate new private key.
  4. Save the resulting JSON to a file readable only by the CP process, e.g. /etc/quazzar/cp/fcm-service-account.json (mode 0600).

Set the env var on the CP host:

CP_FCM_SERVICE_ACCOUNT_PATH=/etc/quazzar/cp/fcm-service-account.json

If this var is unset or the file is unreadable, FCM sends are silently skipped — Android phones still pair, they just won’t receive remote pushes until you provision this.

2. Apple Push Notification service (iOS)

  1. Open the Apple Developer console .
  2. Certificates, Identifiers & Profiles → Keys → Create key.
  3. Enable Apple Push Notifications service (APNs), save and download the .p8 file. Apple shows it once — store it now.
  4. Note the Key ID (10 chars) shown next to the key, and your Team ID (10 chars under your account top-right).
  5. Note the Bundle ID of the Quazzar mobile app (com.quazzar.app by default).

Set four env vars on the CP host:

CP_APNS_KEY_PATH=/etc/quazzar/cp/AuthKey_XXXXXXXX.p8
CP_APNS_KEY_ID=XXXXXXXXXX
CP_APNS_TEAM_ID=YYYYYYYYYY
CP_APNS_BUNDLE_ID=com.quazzar.app

Same fail-safe behaviour as FCM: missing values disable APNs sends cleanly.

3. Verifying the wiring

After restarting CP, hit the CP admin endpoint with a test push:

curl -X POST https://<your-cp>/api/v1/notify \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "<paired-instance-uuid>",
    "title": "Hello from CP",
    "body": "If you see this on your phone, push is working."
  }'

The response includes a results array with one entry per paired device. sent: true confirms a real fan-out; skipped: true with reason “platform fcm/apns not configured” means the matching env vars aren’t set.

Per-plan caps

The License gate enforces a per-day fan-out cap so a noisy alert storm on a free instance can’t drain the FCM/APNs quotas:

PlanMobileInstanceCapMobilePushPerDayCap
Community250
Pro5500
Teamunlimitedunlimited
Enterpriseunlimitedunlimited

Upgrade-required responses follow the canonical upgrade_required shape — the OS upgrade dialog renders the right copy automatically.

Troubleshooting

  • Phones pair fine but no push. Check that CP_FCM_SERVICE_ACCOUNT_PATH (or APNs equivalent) is set and the file is readable by the CP process. Check the CP logs for push.fcm: service account file unreadable or push.apns: key file unreadable.

  • 429 daily push cap reached for this instance. The instance has already hit its daily quota. Either upgrade the plan or wait for midnight UTC (the push_daily_counters row resets per day).

  • Multiple devices on one user. Every paired device gets its own fan-out. To mute a specific device, hit POST /api/v1/devices/<device_id>/mute with {"muted": true}.

  • Mobile pairing — how the QR scan + the pair tunnel work end-to-end.
  • Phase В.4 spec — the /api/cc/notify
    • /api/cc/devices/push-token endpoints on the OS side.
Monitoring SetupLogin