Delivery policy

Send to every browser at once, or to one browser at a time with a fallback.

Each recipient has a delivery policy that decides how a send spreads over its connected browsers. You set it on the recipient's page in the dashboard; your API calls do not change.

Policy	What a send does
all	The default. One attempt goes to every connected browser at the same time.
first	Browsers are tried in the order you set. The first one gets the notification; the next one only gets it when the current one did not show it in time or failed.

How first works#

When the notification is sent, Push writes down the recipient's connected browsers in their order. That list is the plan for this notification.
Step 0 goes to the first browser in the plan.
Push then waits fallbackAfterSeconds (60 seconds unless you change it). If the browser reported the notification as shown, or it was clicked, by then, delivery stops there.
If it was not shown, or if the attempt ends failed, expired or invalid_subscription before the wait is over, Push moves to the next browser in the plan at once.
Browsers that were disconnected since the send are skipped.
This repeats until a browser shows the notification or the plan runs out.

⫻

example

step 0  "Chrome on Windows"   sent at once        no shownAt after 60 sstep 1  "Safari on iPhone"    sent, accepted and shown        stop: nothing else is sent

Each attempt has a step field: 0 for the first browser, 1 for the first fallback and so on. With all, every attempt is step 0.

When a browser counts as shown#

A browser counts as shown when Push's service worker reports that it displayed the notification. See shown.
An attempt the push service accepted but the device never displayed, because it was offline or closed, falls through to the next browser after the wait.
Clicks also stop the fallback. Dismissing a notification does not.

Settings#

Setting	Values
deliveryPolicy	`all` or `first`. Default `all`.
fallbackAfterSeconds	10 to 3,600 seconds. Default 60.
order	Set on the recipient's page. A newly connected browser goes to the end.

Billing#

Every fallback attempt is a normal attempt and counts toward usage when it is created.
A browser that is never reached costs nothing. With first, a recipient with three browsers usually costs one attempt per send instead of three.
If the free allowance and the credit balance cannot cover the next step, the fallback stops quietly.

Changing the policy#

The policy and plan are fixed when a notification is sent. Changes apply to the next send.
A scheduled notification uses the policy and browsers the recipient has when it is released, not when it was created.

NoteTest-key sends follow the same policy. Browser attempts from a test key are never shown, so a first plan falls through to the next browser after the wait.