Send declarative push messages with a service worker fallback

How to do it

A declarative push message is JSON the browser shows by itself, with no service worker code running. The W3C Push API draft defines it. Safari supports it from Safari 18.4 on iOS and iPadOS, for web apps added to the Home Screen. The browser shows it even when a service worker fails or was cleared, and it cannot be abused for silent background work. Browsers without support hand the same payload to your push handler, which parses it and shows the notification. Use a path on your own site for navigate, as Open the exact page the push is about says. Encrypt the payload as Send web push with VAPID and an encrypted payload says.

Examples

JavaScript example

export function declarativePayload({ title, body, path }) {
  return JSON.stringify({
    web_push: 8030,
    notification: { title, body, navigate: new URL(path, 'https://example.com').href },
  });
}

self.addEventListener('push', event => {
  const { notification } = event.data.json();
  event.waitUntil(self.registration.showNotification(notification.title, { body: notification.body, data: { url: notification.navigate } }));
});

Python example

import json
from urllib.parse import urljoin

def declarative_payload(title: str, body: str, path: str) -> str:
    return json.dumps({
        "web_push": 8030,
        "notification": {"title": title, "body": body, "navigate": urljoin("https://example.com", path)},
    })

How to check

A unit test builds the payload for every push type. It checks web_push is the number 8030, notification.title is set and notification.navigate is an https address on your own host. A browser test in a browser without declarative support receives the payload and still shows the notification.

Sources

• W3C Push API, declarative push message

Related rules

• NTF-15 Open the exact page the push is about in Notifications
• NTF-10 Send web push with VAPID and an encrypted payload in Notifications