Push notifications on backd

Devices

Mon, 01 Jan 0001 00:00:00 +0000

A device is one app installation (or one browser) that can receive pushes for a user. Apps register it with POST /_auth/devices; backd owns the registry, so it can move tokens between users, drop them when a session ends and clean up after erasure, which an app’s own collection can’t.

curl -X POST "$BACKD/v1/acme/_auth/devices" \
 -H "Authorization: Bearer $SESSION" -H 'Content-Type: application/json' \
 -d '{"platform": "android", "token": "<FCM registration token>", "name": "Ana'"'"'s Pixel"}'

{"id": "d3c9ljp8hc2g00b6s1m0", "platform": "android", "name": "Ana's Pixel", "created_at": "…", "last_seen": "…"}

The endpoints

All of these need a user session: an API key (or X-Backd-On-Behalf-Of) can’t register devices.

Sending pushes

Mon, 01 Jan 0001 00:00:00 +0000

A function that declares push in its function.yaml has ctx.push.send. The call answers at once; backd’s workers deliver.

export default async function (ctx) {
 const r = await ctx.push.send({
 user: order.owner, // or users: [...], or audience (below)
 kind: "order-shipped", // a template of the realm, or title + body (raw)
 data: { order_no: order.no, eta: "tomorrow" },
 group: `order-${order.id}`,
 priority: "high",
 });
 // r = { send_id: "ps_…", users: 1, jobs: 1, queued: 1, limited: 0, no_devices: 0 }
}

# function.yaml
push: true # or push: { kinds: [order-shipped], audience: false }

Who

Give exactly one of:

Records, test send and metrics

Mon, 01 Jan 0001 00:00:00 +0000

The record of a send

Every send leaves one record, kept for push.send_retention (30 days by default). It holds counts, never content: no title, body, data or token, and no user ids (those live only in the send’s jobs, which follow the realm’s job retention).

Field	Meaning
`id`, `kind`, `sender`, `created_at`	The send, its template kind (`raw` for a message the function wrote), who sent it (`function:<database>/<name>` or `admin:<actor>`) and when
`users`	How many users were named; `null` for an audience
`queued`, `limited`, `no_devices`, `no_consent`	Users handed to delivery, users over their limit, users with no device to reach (a silent push skips browsers), users who don’t hold the consent the send requires
`sent`, `invalid`, `failed`	Devices the provider accepted, devices removed as dead, devices not delivered to
`planned`, `batches`, `batches_done`, `units`, `units_done`	How far the work is
`completed`, `completed_at`	Everything is done

backd push sends --realm acme # the latest, newest first
backd push sends --realm acme --kind order-shipped
backd push sends --realm acme --function main/notify --limit 10
backd push sends --realm acme --id ps_d3c9ljp8hc2g00b6s1m0

The admin interface shows the same on its Push page (Admin interface). The admin API: GET /_admin/push (the configuration state and the secrets still missing), GET /_admin/push/sends (filters kind, function, since, until, limit, skip) and GET /_admin/push/sends/{id}. Both need the functions area, and read-only administrators may use them.

Local development

Mon, 01 Jan 0001 00:00:00 +0000

You don’t need a device or a provider key to develop with push.

The capture provider

Give a platform provider: capture: the worker then stores each delivery in a push_outbox collection of the realm’s system database instead of calling a provider, with the message as it would have gone out and the outcome the device was given.

push:
 android: { provider: capture }
 web:
 provider: capture

It needs no credentials and no secrets, but it stores message content, so startup refuses it unless BACKD_DEV=true. Captured deliveries are kept for 24 hours.

FCM: Android, and iOS apps on the FCM SDK

Mon, 01 Jan 0001 00:00:00 +0000

FCM is the provider for Android, and for iOS apps that use the FCM SDK (ios.provider: fcm). backd sends through FCM’s HTTP v1 API from the worker, with an OAuth2 access token it mints from a service account.

1. A Firebase project

Open the Firebase console and create a project, or pick the one your app uses.
Android: add an Android app with your application id (the package name). Download google-services.json for the app’s build.
iOS over FCM: add an iOS app with the bundle id, download GoogleService-Info.plist, and upload an APNs authentication key under Project settings → Cloud Messaging → Apple app configuration (see APNs for where it comes from). That key lives in Firebase: backd never sees it.
In the linked Google Cloud project, enable the Firebase Cloud Messaging API (V1) (APIs & Services → Library). The legacy API is not used.

2. A service account

Project settings → Service accounts → Generate new private key. A JSON file downloads: it holds project_id, client_email and private_key.
Store it as a realm secret, from the file:

backd secret set --realm acme --name FCM_SERVICE_ACCOUNT < service-account.json

The value is read from standard input, newlines included, and encrypted with the instance’s BACKD_SECRETS_KEY. Delete the downloaded file afterwards.

APNs: iOS

Mon, 01 Jan 0001 00:00:00 +0000

ios.provider: apns sends to iPhones and iPads directly through Apple’s push service: HTTP/2, authenticated with a token signed by a key you create in your Apple Developer account. (Apps on the FCM SDK use FCM instead.)

1. The key

In the Apple Developer account: Certificates, Identifiers & Profiles → Keys → +. Name it, tick Apple Push Notifications service (APNs), and continue.
Download the .p8 file: it can be downloaded once. Note the 10-character Key ID shown.
Note your Team ID: the 10 characters at the top right of the account’s Membership details.
The topic is your app’s bundle id (for example com.acme.app). The app’s App ID must have the Push Notifications capability enabled.

2. The secret

backd secret set --realm acme --name APNS_KEY < AuthKey_AB12CD34EF.p8

The file is read as it is, newlines included.

Web Push: browsers

Mon, 01 Jan 0001 00:00:00 +0000

web.provider: webpush sends to browsers with the standard Web Push protocol: no account with a vendor, only a VAPID key pair that identifies your realm to the browsers’ push services (Google, Mozilla, Apple, Microsoft).

1. The key pair

backd push web-keys --realm acme

It generates a P-256 key pair, stores the private half as the realm secret VAPID_PRIVATE_KEY, and prints the public half with the realm.yaml snippet:

push:
 web:
 provider: webpush
 public_key: BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U
 private_key: secret:VAPID_PRIVATE_KEY
 subject: secret:VAPID_SUBJECT

2. The subject

Browsers’ push services use a contact URI to reach you when something goes wrong with your pushes:

From apps: the JavaScript client

Mon, 01 Jan 0001 00:00:00 +0000

The JavaScript client has client.push, a small layer over the device endpoints. It needs a user session: an API key can’t register devices.

const device = await backd.push.register({ platform: 'android', token: fcmToken, name: "Ana's Pixel" })
const mine = await backd.push.devices() // [{ id, platform, name, created_at, last_seen }] (never a token)
await backd.push.unregister() // the device this client registered; or unregister(id)

Call	What it does
`register({ platform, token, name? })`	`POST /_auth/devices`. Registers or refreshes; keeps the returned id (`client.push.deviceId`) for `unregister()`
`devices()`	`GET /_auth/devices`
`unregister(id?)`	`DELETE /_auth/devices/{id}`; without an id, the device this client registered (`false` when there is none)
`registerOnLaunch(getToken, { onError })`	Registers now if signed in and again after every sign-in. `getToken` returns what to register, or `null` while the app has no token. Returns a function that stops it
`subscribeWeb({ registration, name?, requestPermission? })`	Subscribes a browser and registers the subscription (below)

Keeping a device registered

A device is removed when its session ends, when it is unseen for push.devices.stale_after, and when its realm’s web key is rotated. So an app registers at every launch and after every sign-in, which is what registerOnLaunch does:

Push notifications on backd

Devices

The endpoints#

Sending pushes

Who#

Records, test send and metrics

The record of a send#

Local development

The capture provider#

FCM: Android, and iOS apps on the FCM SDK

1. A Firebase project#

2. A service account#

APNs: iOS

1. The key#

2. The secret#

Web Push: browsers

1. The key pair#

2. The subject#

From apps: the JavaScript client

Keeping a device registered#

The endpoints

Who

The record of a send

The capture provider

1. A Firebase project

2. A service account

1. The key

2. The secret

1. The key pair

2. The subject

Keeping a device registered