Skip to Content
Pocket Notifier

Push delivery

How the Worker talks to FCM directly, and how the Android app turns data messages into notifications.

Decided The Worker sends to FCM HTTP v1 itself. There is no Expo push service or other relay in between.

Why data-only messages

FCM has two kinds of message:

Notification messageData-only message
Who draws the notificationThe Android system, when the app is in the backgroundThe app, always
Channel per priorityOnly the channel ID✓
Grouping per projectLimited✓
Action buttons and inline reply✗✓
Dismiss on other devices✗✓

notifier needs everything in the right-hand column, so every push is data-only and the app builds the notification itself.

Sending from the Worker

Get an OAuth token

Sign a JWT with the Firebase service account key using WebCrypto (RS256), and exchange it at https://oauth2.googleapis.com/token for an access token with the firebase.messaging scope. Cache it in memory until 60 seconds before it expires; it lasts about an hour.

The cache is keyed by a SHA-256 fingerprint of the private key, so a rotated key gets its own token even when client_email stays the same. Concurrent sends share one exchange. The key is imported once per secret value when the Worker first needs it; a key that does not import disables push.

Send one request per device

POST https://fcm.googleapis.com/v1/projects/<project-id>/messages:send
Authorization: Bearer <oauth-token>
Content-Type: application/json

{
  "message": {
    "token": "<device push token>",
    "data": { "v": "2", "kind": "message", "id": "msg_...", "...": "..." },
    "android": { "priority": "HIGH", "ttl": "86400s" }
  }
}

data follows the push payload contract.

Handle the response

FCM responseAction
200Done
UNREGISTERED error code, or 400 INVALID_ARGUMENT on the tokenDelete the device row
401Drop that access token (only if it is still the cached one) and try once more with a new one
429 or 5xxRetry with backoff (200 ms, 400 ms, or Retry-After capped at 2 s), at most 3 tries
Network error or timeoutLog it and do not resend: the request may have reached FCM, and a resend could show the notification twice
Anything else, including a bare 404Log it and keep the device

A bare 404 without UNREGISTERED usually means a wrong project ID, so it never deletes devices. Every FCM and OAuth request times out after 8 seconds.

Logs carry only a reason code (dead_token, rate_limited, server_error, timeout, auth, unknown) and the numeric HTTP status, never response text, tokens, keys or payloads.

Fan-out. On publish, the Worker sends to every Android device of users who are members of the project and subscribed to it without muting, the publisher included. Up to 6 requests run at once, inside executionCtx.waitUntil, so the publish response never waits for FCM. Dead devices are deleted in one statement at the end.

Right before each send, the Worker checks that the device still has the same token and still belongs to the same user. A phone that switched accounts while the push was queued is skipped.

Limits. One publish or markRead makes at most 40 FCM requests, retries included. When more devices qualify, the most recently seen get the push first, and the rest are logged as push truncated=<n>. That is plenty for a small invited group. Open Larger fan-outs move to a Cloudflare Queue later.

FCM priority. Messages with priority 4–5 are sent as HIGH so they wake the phone right away. Priority 1–3 are sent as NORMAL, and Android may hold them back a little to save battery. dismiss pushes are always NORMAL.

Dismiss. When messages.markRead marks messages as read, the Worker sends dismiss with only the newly marked ids to all of that user's Android devices. The API does not know which device the read came from, so the reading device gets it too, which is harmless.

Secrets. The service account JSON is stored as the Worker secret FCM_SERVICE_ACCOUNT and never committed. The project ID is read from it. The secret is optional: without a usable one, push is disabled, publishing still works, and each request logs push disabled at debug level.

Code. The sender, payload builder, fan-out and dispatch live in packages/api/src/push/. They take fetch, the clock and the database as inputs, so they are tested in Node with no Workers globals. apps/server/src/dispatch.ts connects them to waitUntil and gives each background task its own logger, because the request's log has usually been emitted by the time the push runs.

Receiving on Android

The app has to build the notification even when it is not running.

Decided A small Kotlin module in apps/native/modules/notifier-push handles it. It contains a FirebaseMessagingService whose onMessageReceived:

  1. parses the payload,
  2. picks the priority channel,
  3. draws or loads the conversation and sender avatars,
  4. sets the group and actions,
  5. posts the notification natively.

No JavaScript has to start, which keeps it reliable when the app has been killed. The module also creates the five channels on first launch and forwards onNewToken to the app for device registration.

expo-notifications with a background task was the alternative. It was rejected because it needs a headless JS runtime for every push, and building chat-style notifications from JavaScript is limited.

Device tokens

  • The app registers the raw FCM token from getDevicePushTokenAsync() with devices.register on every launch and whenever onNewToken fires. Registration upserts by token.
  • Signing out calls devices.remove for the current device. Without that, the phone would keep getting the previous user's pushes.
  • Devices not seen for 60 days are deleted by the retention job.

iOS

Not in v1. The server only pushes to devices registered as android: an iOS device token is an APNs token, which FCM would reject, and the device would then be deleted as dead. FCM can also deliver to iOS through APNs, so the sender may be reused, but a data-only message on iOS needs a Notification Service Extension to change the content. That will be decided when iOS work starts. Open

On this page