Push notifications

The push channel delivers alerts to the Android app through Firebase Cloud Messaging.

Setup

1. Create a Firebase project and enable Cloud Messaging.

2. Create a service account with permission to send messages, and download its JSON key.

3. Give the whole file to Watcher, verbatim, as a single environment variable:

   .env

   FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"...","client_email":"...","private_key":"..."}

   Caution

   Paste the file contents exactly. Malformed JSON, or a private_key whose newlines were mangled, stops Watcher from starting — deliberately, so you find out at deploy time rather than when an alert fails.

4. Build and install the Android app, point it at your instance, and sign in. The app registers its device token automatically.

5. Add push to a watch’s channels and force a run to test.

How delivery works

• An alert fans out to every device token registered to the watch’s owner.
• Delivery counts as successful if at least one device accepted it.
• Tokens the provider reports as gone (uninstalled app, rotated token) are pruned automatically.
• Messages are data-only: the app renders the notification itself, so device-side preferences — which tiers to show, quiet hours — are honoured even when the app is closed.

Watcher mints its own short-lived access token from the service account using standard cryptography; there is no Firebase SDK dependency on the server.

No devices means failed delivery

If the owner has no registered device, delivery fails rather than being skipped. That is intentional — the alert is then queued and retried instead of disappearing — but a push-only watch on an account with no device will keep producing notify-failed runs until a device registers. Pair push with telegram if you want a fallback route.

Managing device tokens directly

The app handles this, but the routes are open to any client:

curl -s -X PUT "https://<your-host>/devices/<token>" \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"platform":"android"}'

See Devices API.

Platform support

Android only. The iOS project in the repository is unmaintained, and the device platform field currently accepts android alone.

Security notes

• The service-account JSON is a credential: it can send messages as your project. Keep it in the environment or a secret store.
• Watcher never logs it, and its errors report status codes only — never the key material or the device token.
• Registration tokens are device addresses, not secrets, but they are still scoped per owner and never returned to other accounts.