Push notifications on back(d)

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.

From apps

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 back(d)

Devices

The endpoints#

Sending pushes

Who#

Records, test send and metrics

The record of a send#

From apps

Keeping a device registered#

The endpoints

Who

The record of a send

Keeping a device registered