Push Notifications: Client API

The browser SDK gains a client.push object.

App icon badge

The badge is the red number on an installed app's icon. Set it in any push with badge, and from the page with client.push.setBadge(). It's a plain number you choose, such as unread messages or open orders, and 0 clears it.

Where badges aren't supported, badge is silently ignored and the notification still shows. Your code never has to check.

Set it with a push

The number is the same for every device in one send. For a count that differs per person, like each user's unread messages, send to each user separately:

addDbTrigger("set", ["chats", "$chatId", "messages", "$msgId"], (context) => {
  if (context.dataBefore !== undefined) return;
  const msg = context.dataAfter;
  const unread = increment(["users", msg.to, "unread"], 1).data;   // the recipient's new total
  sendPush(["users", msg.to, "pushTokens"], {
    title: msg.fromName,
    body: msg.text,
    url: `/chats/${context.path[1]}`,
    badge: unread
  });
});

Clear it when they've caught up

Opening the app doesn't clear the badge on its own. Set it when the user has seen things, and keep your stored count in step:

async function openInbox() {
  showInbox();
  await client.set(["users", myUid, "unread"], 0);
  client.push.setBadge(0);          // this device, right now
}

Make the app installable

iPhones only deliver push to apps added to the Home Screen, and an installed app also looks and feels like a real app on Android. Two things make that possible: a manifest file and an icon. New projects include both. For an existing project, add them like this:

{
  "name": "Pawsbook",
  "short_name": "Pawsbook",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4361ee",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

<link rel="manifest" href="/manifest.webmanifest">
<link rel="apple-touch-icon" href="/icon-192.png">
<meta name="theme-color" content="#4361ee">

The service worker

public/sw.js is an engine file, like sdkmod.js. The SDK registers it on every page, whether or not the app uses push. It does five things:

• Keeps a page cache. See below: the app opens instantly from the last copy seen, and opens at all with no signal.
• Sets the badge. When a push carries badge, it updates the app icon number, even if the app is closed.
• Shows every push. It always displays a notification, even for a damaged payload (falling back to "New update"). Apple cancels subscriptions for apps that receive pushes without showing one.
• Handles taps. It focuses an open window of your app or opens the payload's url, and only ever within your own site.
• Updates itself immediately. A new version takes over the next time the app is opened.

The page cache

On by default. Every same-origin GET the page makes — the HTML, sdkmod.js, your scripts, styles, images and manifest — is answered from the worker's cache when a copy exists, and the current copy is fetched in the background and stored for next time. This is stale-while-revalidate: a page the user has seen before opens at once, even on a slow connection, and with no network at all it still opens. A page never opened on that device gets a small built-in "You're offline" page instead of the browser's error.

Nobody is left on an old build. Every load re-fetches in the background (serveStatic answers 304 cheaply when nothing changed), and when the fetched copy differs from the stored one the worker tells every open window. The SDK reloads the page by itself only when that happens within a few seconds of load and before the user has typed, tapped or scrolled — on a fast connection that is an invisible refresh. After that it is your app's call through client.onUpdate, which is the place for a "new version available" notice:

const client = await createClient();

client.onUpdate(() => {
  showBanner("A new version is ready", { action: "Reload", onClick: () => location.reload() });
});

// Or turn the page cache off for this app. Push keeps working.
const client = await createClient({ pageCache: false });

What is never cached: anything cross-origin; anything but GET; the WebSocket, which the worker never sees; the file store under /_file/, which is rule-governed; any response carrying Cache-Control: private or no-store, which is how a route of your own stays out; any non-200; anything over 8 MB. The cache keeps at most 500 entries, oldest dropped first. Files served to a signed-in person by an auth-gated serveStatic mount are marked private by the engine and never stored — see Serving Static Files.

Page cache: troubleshooting