Definition

Declarative Web Push

Short definition

Declarative Web Push is a format where the push message payload itself is a JSON object describing the notification (title, body, icon, and so on) that the browser displays directly, rather than requiring a service worker's push event handler to run arbitrary JavaScript to call showNotification(). WebKit introduced it partly to allow more efficient and more private push delivery on iOS/Safari.

Reviewed August 7, 2026

A declarative payload sets a specific content-encoding and a JSON body shaped like {"web_push": 8030, "notification": {"title": "New message", "body": "You have a new message", "navigate": "/inbox"}}, letting the OS render the notification without waking the page's JavaScript at all in the common case.

This differs from the traditional model, where every push wakes the service worker to execute a push event handler that must itself call self.registration.showNotification() — useful for custom logic, but heavier and, on some platforms, subject to tighter execution-time limits.

WebKit's stated motivation is battery and privacy: declarative pushes can be delivered and displayed without spinning up a JavaScript execution context for every single notification, and Safari on iOS adopted this model as part of its web push implementation.

See the WebKit blog post introducing the feature for the full payload schema and rationale: https://webkit.org/blog/16535/meet-declarative-web-push/.

Related terms

Push API

The Push API lets a service worker subscribe to a browser-run push service and receive encrypted messages from a server at any time, including when no tab or window for the site is open. Subscribing is done with registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey }), and incoming messages arrive in the worker's push event.

push event (service worker)

The push event fires on the service worker whenever a message arrives from the push service the browser is subscribed to. A handler typically reads event.data.json() for the payload and calls event.waitUntil(self.registration.showNotification(title, options)) so the browser keeps the worker alive until the notification is actually displayed.

Notification permission states

Notification.permission returns one of three strings: "default" (the user has not yet decided, so the site may still call Notification.requestPermission() to ask), "granted" (the site may show notifications), or "denied" (the site is blocked from showing notifications and, critically, cannot re-prompt programmatically once denied).

appinstalled event

appinstalled is a window event, listened for with window.addEventListener("appinstalled", () => { ... }), that fires after the browser has finished installing the PWA — regardless of whether the install was triggered via the native beforeinstallprompt flow or a browser menu item. It fires exactly once per successful install and carries no event detail beyond the fact that installation completed.

Related applications

WebAPK

A WebAPK is a small, real Android application package that Chrome generates and signs on the fly (via a Google-run server) when a user installs a qualifying PWA on Android. It gives the installed site a genuine entry in Android Settings > Apps, its own task-switcher identity separate from Chrome, and the ability to be the registered handler for its own scope's URLs.