Service Workers

The Service Worker Engine

A service worker is a small piece of code the browser keeps running for your site. It is what makes offline caching and push notifications possible.

Where to find it

Architect Panel → Configuration:

• Site Settings — the Progressive Web App and Service Workers option groups

Architect Panel → Layout & Pages:

• Dependencies — the files the site loads, and what the offline cache is built from

Architect Panel → Background Messaging:

• Push Notifications — the VAPID keys web push needs

The switches

• Enable Service Worker Engine — the master switch. Off, none of the rest applies and the service worker is not served at all.
• Enable Offline Cache Engine — caching of pages and resources.
• Enable Push Notification Engine — web push.

Then three scope switches decide where the offline cache applies:

• Main website
• Web app
• Admin panel

The scopes are separate for a reason

Each gets its own service worker with its own file list. So you can cache the web app aggressively — where the audience is known and the content is stable — while leaving the administration panel uncached, where staleness would be confusing and the audience is small.

Start with the web app scope only

It is the scope with the clearest benefit and the smallest blast radius. Prove it works there before extending to the main website, and think hard before enabling it on the admin panel.

Caching the admin panel is rarely worth it

Administrators are usually on good connections at a desk, and a cached administration interface showing yesterday’s assets while somebody debugs a problem is actively harmful.

Service workers are sticky

The most important operational fact. Once installed in somebody’s browser, a service worker persists — it survives page reloads and keeps serving cached content.

So a mistake in what you cache reaches users and stays with them, and it is not fixed by you correcting the configuration alone.

They need HTTPS

Service workers do not run over plain HTTP. That is a browser rule and there is no way round it.

Test in a private window

Because your own browser will have an old service worker and an old cache, and you will spend an afternoon debugging something that was fixed twenty minutes ago. A fresh private window has neither.

Know how to clear one

Before you enable anything. In the browser’s developer tools, under Application, a service worker can be unregistered and its caches cleared. That is the answer to almost every strange caching problem, and it is what you will be talking a user through.

Worked example

An organisation enabled the engine with offline caching on the web app scope only, tested in private windows, and wrote a two-line support note on unregistering the service worker. The main website scope was added a month later; the admin panel was left off deliberately.

Recommendations

• Web app scope first, alone.
• Leave the admin panel uncached.
• Test in private windows, always.
• Write the "unregister it" note before you need it.

Web Push Notifications

The push engine lets the site send notifications to a user’s device, even when they do not have it open.

Where to find it

Architect Panel → Background Messaging:

• Push Notifications — the VAPID keys web push needs

Architect Panel → Configuration:

• Site Settings — the Progressive Web App and Service Workers option groups

What it needs

Web push is signed with a key pair — a public key given to browsers and a private key held by the server. The Push Notifications setup screen shows whether both are present and can generate them if they are not.

Generation is a one-time act. Once keys exist and browsers have subscribed against the public key, replacing them invalidates every existing subscription.

Do not regenerate keys casually

The setup screen refuses to overwrite keys that are already configured, which is the right behaviour. Regenerating means every subscriber silently stops receiving notifications, and there is no message telling anybody.

The user has to agree

Browsers require permission, asked once. If somebody declines, you cannot ask again in any useful way — the browser remembers, and re-enabling means the user going into their own settings.

So the one prompt you get is worth spending.

Ask at the right moment

Not on arrival. Somebody who has just done something that would benefit from a notification — booked an appointment, raised a request, subscribed to an update — understands what they are agreeing to.

Explain what you will send before the browser prompt appears, so the prompt confirms a decision rather than posing a question.

Send few, and send useful

A notification interrupts somebody. The threshold should be "would they want to be interrupted for this", which is a much higher bar than "is this a thing that happened".

Organisations that send everything end up with users who have disabled everything.

The message is short

A title and a line of text. Say what happened and what it concerns; there is no room for anything else, and the notification is a prompt to open the app rather than a substitute for it.

Do not put anything private in it

Notifications appear on locked screens, visible to whoever is holding the phone. A name, a case reference or a medical detail in a notification is that information shown to a stranger on a train.

It is not reliable delivery

Push is best effort. Devices are off, subscriptions expire, browsers drop them. Anything that must reach somebody needs e-mail or another channel as well.

Worked example

A service asks for push permission immediately after a user books an appointment, having explained that it is used for reminders and changes only. Notifications say "Your appointment has moved" without naming the service. Roughly two thirds accept, and unsubscription is negligible.

Recommendations

• Generate keys once and never casually replace them.
• Ask after a relevant action, having explained first.
• Nothing private in the text — it shows on lock screens.
• Pair with e-mail for anything that must arrive.