How push notifications reach operators

Publishing changes what the next sync hands over; it does not, by itself, reach into anyone's pocket. A push notification is the separate nudge that tells operators something is waiting. By the end of this page you will know the two ways a push is sent, how ROK picks who gets it, how operators choose what they hear about, and what happens when delivery fails.

Two ways a push is sent

By hand. On a published item, people who hold Publish see a Notify operators card on the edit page. Send notification sends one push about that item straight away and reports the result on the card — "Sent to 17 devices (14 operators) — delivery confirmations arrive within ~15 minutes." The function that sends it checks again, on the server, that the caller holds Publish in the agency they are working in. The card belongs to the Operator push notifications module; switch that off in Settings → Features (opens the admin console) and the card disappears.

Automatically, when a scheduled publish goes live. The background job that publishes scheduled items queues a push for each one, and that is the only automatic push. Publishing by hand sends nothing on its own. The module switch does not affect it: scheduled publishes notify whether or not the card is shown. See scheduled publishing.

Either way, the push is titled with your agency's name, with "New:" or "Updated:" and the item's title underneath — "Metro Fire" over "New: Swiftwater entry" — so someone in two agencies can tell which one it came from. A critical item is titled "Metro Fire — critical", and each phone is also sent a silent message that wakes the app to sync in the background, so the procedure is on the phone before anyone taps anything.

Who gets it

Both paths use the same rules. A push goes to everyone who is an active member of your agency (staff included, if they use the app), opted in for the item, and holding a registered phone. A suspended agency sends no pushes.

On the card, "operators" counts the people who matched; "devices" counts the phones the push service accepted the notification for. Someone with no registered phone is counted as an operator and receives nothing.

Accepted is not delivered

The push service (Expo) accepting a notification only means it will pass it on. Apple or Google do the actual delivery, and report back with a receipt a few minutes later. ROK collects receipts every 15 minutes and keeps a record of every push — manual or scheduled — which publishers see as the Delivery record on the item's Notify operators card: messages delivered, failed, and still awaiting confirmation. A receipt that never arrives within two hours is counted as a failure ("Unconfirmed"). ROK's platform team watches the same receipts across every agency, which is how a fault on Apple's or Google's side is caught instead of looking like a quiet week.

Preferences follow top-level guides

In the app, under Settings → Notification preferences, each operator has a Push notifications switch and an All guides switch. With All guides off they choose from Only these guides, a list of the agency's top-level guides. Preferences are kept per agency, and saving them needs a connection.

ROK matches an item to the top-level guide or guides it sits in, looking up through a sub-guide if it is nested. Then:

• No saved preference counts as opted in to everything. Never having opened the screen is not opting out.
• Push notifications off means no pushes at all from this agency.
• A guide list means pushes for items inside those guides, plus anything that sits in no guide at all — which goes to everyone with notifications on. A newly published top-level guide is itself in no guide, so it is announced to everyone.

A guide list is fixed when it is saved: items in a top-level guide created later do not match it until the person adds that guide.

Phones register themselves

The app registers the phone when someone signs in, when it reopens with a saved session, and whenever Notification preferences is opened — provided the phone's own notification permission is granted. The registration belongs to the person, not the agency, so someone in two agencies gets each agency's pushes on the same phone, filtered by that agency's preferences.

When the push service reports that a phone is no longer registered — for example, after the app was uninstalled — ROK deletes that registration so it stops being tried.

The queue makes scheduled pushes durable

A scheduled push is not fire-and-forget. The database keeps it in a queue that is worked every minute, and holds each entry until the sending function reports back:

• Sent — done. A partial delivery counts as sent, because a retry would notify again everyone who already got it.
• Skipped — nothing to send: the item was unpublished again before its turn, or the agency was suspended.
• Failed — tried again after 1, 2, 4, 8 and then 16 minutes. An attempt that does not report back within 3 minutes counts as failed too. After six attempts in all the entry is marked dead, and ROK's platform team sees it.

Delivery is at least once: if a push went out but its report was lost, it is sent again, so an operator can occasionally receive the same notification twice.

A manual send has none of this. It is one attempt, the card shows what happened, and if it failed you send it again. Either kind appears in the item's delivery record.

Tapping a notification

Tapping a push opens the app, which runs a sync first and then opens the item if it is on the phone. With no signal the tap still opens the app, but an item the phone has never synced appears only once a sync gets through.

In practice

• A push is a prompt, not the delivery. Operators get the content at their next sync either way. See how offline reading works.
• Signing out silences a phone. Signing out of the app removes the phone's registration for that person (when the phone is online at the time), and on a shared phone the notifications follow whoever signs in next. A phone that is lost can be signed out remotely — see Sign out & wipe on the person's page under User detail.