Concept in Notifications
Web Push on iOS and iPadOS (16.4+)
Published Updated
Web Push lets Home Screen web apps receive notifications on iOS and iPadOS 16.4 (2023-03)
and later. It uses the same Push API, Notifications API, and service worker combination as
desktop, with delivery through the Apple Push Notification service. The user must install the
app and tap a control to request permission before push is available. In a Safari tab on iPhone the Notification interface does
not exist, so an uninstalled site cannot request permission.
How it works
Section titled “How it works”WebKit gates the whole feature on installation. A site becomes a Home Screen web app when the
user chooses “Add to Home Screen” from the Share menu and the manifest’s display member is
standalone or fullscreen, or the page carries the apple-mobile-web-app-capable meta tag; with
neither, the icon is a Home Screen bookmark that, from 16.4, opens in the user’s default browser,
where push is unavailable (Web Push for Web Apps on iOS and iPadOS,
webkit.org). Browser-compat-data words the same gate as a “non-default display value”. From 16.4 third-party browsers can offer the same Share-menu item, and the resulting
app opens as a web app regardless of which browser added it.
What a Safari tab exposes
Section titled “What a Safari tab exposes”Browser-compat-data records the iOS entry for Notification as 16.4, partial, with two notes:
the interface is undefined unless the page is a web app saved to the Home Screen with a
non-default manifest display, and a notification can only be sent from a service worker
(api.Notification, safari_ios). Notification.requestPermission()
in a tab throws ReferenceError, not a rejected promise, and new Notification() has no
supported path on the platform at all; from script, registration.showNotification() is the only
way to display one. The exception is a Declarative Web Push message (18.4+, below), which the
browser displays itself with no JavaScript.
Permission, subscription, and delivery
Section titled “Permission, subscription, and delivery”Inside the installed app, the permission request must follow direct user interaction, such as a
tap on a subscribe button; iOS then shows the system notification prompt, and the user manages
the result per web app under Settings > Notifications like any native app. pushManager.subscribe()
requires userVisibleOnly: true and a VAPID applicationServerKey; the returned endpoint is on a
*.push.apple.com host, which servers that allow-list push endpoints must permit. WebKit revokes a
subscription whose push events do not result in a visible notification (Meet Web
Push, webkit.org), so a handler that swallows a
message, or fails before showNotification(), loses the subscription, not just that alert.
In the OpenPWA device test on iOS 18.6.2 (2026-10-20), a Notification.requestPermission()
call from a tap in a never-prompted Home Screen app stayed pending for 2068 ms, until the operator
answered the system prompt, and resolved "granted"; in a zh-CN interface the prompt read
““Perm Test”想给你发送通知” (study, notebook N54,
N59). One grant set both the registration’s and window.pushManager’s permissionState to
granted.
Notifications integrate with Focus, and Focus settings sync across devices for web apps whose
manifest id and user-chosen name match. The Badging API (navigator.setAppBadge()) shipped in
the same release for Home Screen web apps, with the badge shown once notification permission is
granted.
Declarative Web Push (18.4+)
Section titled “Declarative Web Push (18.4+)”iOS and iPadOS 18.4 added a second flavour for Home Screen web apps, and Safari 18.5 brought it to
macOS: window.pushManager (BCD api.Window.pushManager: Safari 18.4) lets a page subscribe
without a service worker, and a push message in the declarative JSON format ("web_push": 8030
plus a notification object) is displayed by the browser with no JavaScript. A service worker, if
present, may still modify the notification; if its handler fails, the declarative message is shown
as the fallback, so the revocation rule does not apply to this path (Meet Declarative Web
Push, webkit.org). The same post says a
registered service worker “scoped to the root level of your website domain” shares the window’s
push subscription; a worker scoped to a subpath is not covered by that sentence.
In the OpenPWA device test on iOS 18.6.2, a Home Screen app used a service worker scoped to a subpath (/demo/ and a lab path under /lab/). A subscription made
through the registration was not returned by window.pushManager.getSubscription(), which gave
null; a root-scoped worker was not tested. And window.pushManager was exposed in a plain Safari
tab, where Notification and PushManager are not, so 'pushManager' in window does not show that
push can be used (study, notebook N03, N33,
N41).
Notification clicks in the installed app
Section titled “Notification clicks in the installed app”Browser-compat-data records notificationclick on ServiceWorkerGlobalScope as unsupported on
Safari for iOS (api.ServiceWorkerGlobalScope.notificationclick_event, version_added: false).
On the BCD issue about that entry, a BCD contributor explains that the collector tests
"onnotificationclick" in self in a service worker and that the test fails on iOS 16, 17 and 18,
while developers report the event firing in installed apps
(mdn/browser-compat-data#22959,
github.com). WebKit bug 268797 is open with reports of the event not firing when the user taps a
notification while no page of the app is alive (Bug 268797,
bugs.webkit.org).
The property depends on the context that controls the worker, which allows both reports to be true.
On iOS 18.6.2 the same worker script reported 'onnotificationclick' in self as false when a
Safari tab controlled it and true when the Home Screen app did, and notificationclick fired in
the app on all six test taps, each with a window alive (see the field note below). Register the handler
unconditionally; do not gate it on a feature test run outside the installed app.
Support position
Section titled “Support position”Safari 16.1 on macOS Ventura shipped Web Push first (2022-10; WebKit’s iOS 16.4 post names the
release), with delivery through the webpushd
daemon so that Safari need not be running. iOS and iPadOS 16.4 followed for Home Screen web apps
only (both platforms have compat data). BCD records no Push API in Android WebView
or in iOS WebViews inside other apps (api.PushManager). Chrome for Android has supported push in
a browser tab since version 42 with no install step, though Samsung Internet and Opera for Android
do not show notifications in incognito mode (BCD api.Notification).
Examples
Section titled “Examples”On iOS the examples work only inside the installed app; elsewhere they need a browser with push support and an HTTPS page.
Routing an uninstalled iPhone visitor to install guidance
Section titled “Routing an uninstalled iPhone visitor to install guidance”The 'Notification' in window test is the install check on iOS: it is false in a tab and true
in the Home Screen app. The same test is also the right first step everywhere else, so no
platform sniffing is needed.
async function enablePush(registration, applicationServerKey) { if (!('Notification' in window)) { showAddToHomeScreenGuidance(); // iOS tab or embedded web view: install first return null; } const permission = await Notification.requestPermission(); if (permission !== 'granted') return null; return registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey });}Call enablePush() from a tap handler: WebKit requires the permission request to follow direct
user interaction, and in the iOS 18.6.2 device test the prompt appeared after a tap.
Keeping the userVisibleOnly promise in the push handler
Section titled “Keeping the userVisibleOnly promise in the push handler”For a classic (non-declarative) push message, every push event must end in showNotification(),
including the error path, or WebKit revokes the subscription. A generic fallback notification is safer than none.
self.addEventListener('push', (event) => { event.waitUntil((async () => { let payload = { title: 'Update available', body: '' }; try { payload = event.data.json(); } catch { // malformed payload: still show something, or the subscription is revoked } await self.registration.showNotification(payload.title, { body: payload.body }); })());});Keep the try/catch on iOS: a server bug that sends a malformed body could otherwise
silently unsubscribe every iPhone user, making this safeguard more important there.
Querying the push manager the subscription was made with
Section titled “Querying the push manager the subscription was made with”Probe for the manager you subscribed with rather than for the PushManager interface.
window.pushManager is the declarative path, but on iOS 18.6.2 it is also exposed in a Safari tab
where push cannot be used, and with a worker scoped below the site root it does not return the
worker’s subscription. Check for Notification first, then prefer an active registration.
async function getPushManager() { if (!('Notification' in window)) return null; // iOS tab or web view: window.pushManager may still exist const registration = 'serviceWorker' in navigator ? await navigator.serviceWorker.getRegistration() : undefined; if (registration?.active) return registration.pushManager; // the manager classic Web Push subscribed with return 'pushManager' in window ? window.pushManager : null; // Declarative Web Push, Safari 18.4+}getRegistration() settles with undefined when nothing is registered; navigator.serviceWorker.ready
would wait forever in that case, which is why the probe avoids it. With a worker scoped below the
site root, an app that moves from one manager to the other has to call getSubscription() on the
one it used, or it may read null and subscribe again.
See also
Section titled “See also”- Web Push for Web Apps on iOS and iPadOS (webkit.org)
- Meet Declarative Web Push (webkit.org)
- Push API (w3.org)
- Web Push and PushManager.subscribe()
- Add to Home Screen on iOS
- Notification.requestPermission()
- Badging API
- Testing Home Screen web apps on iOS 18.6.2
- mdn/browser-compat-data#22959 (github.com)
Specifications
| Specification | Status |
|---|---|
| Web Push | W3C |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 42 | high | source | 1 |
| Chrome (Android)# | Yes | 42 | high | source | 23 |
| Edge (Desktop)# | Yes | 17 | high | source | 4 |
| Firefox (Desktop)# | Yes | 44 | high | source | 5 |
| Firefox (Android)# | Yes | 48 | high | source | 6 |
| Safari (macOS)# | Yes | 16 | high | source | 7 |
| Safari (iOS)# | Yes | 16.4 | high | source | 8 |
| Samsung Internet# | Yes | 4.0 | high | source | 910 |
| WebView (Android)# | No | — | high | source | 11 |
| Safari (iOS) · Declarative Web Push# | Yes | 18.4 | medium | source | 121314 |
- The `options` parameter with a `applicationServerKey` value is required.
- The `options` parameter with a `applicationServerKey` value is required.
- Derived by browser-compat-data mirroring from Chrome.
- The `options` parameter with a `applicationServerKey` value is required.
- From Firefox 72 onwards, can only be called in response to a user gesture such as a `click` event.
- From Firefox Android 79 onwards, can only be called in response to a user gesture such as a `click` event.
- Notifications are supported on macOS Ventura and later.
- Notifications are supported in web apps saved to the home screen.
- The `options` parameter with a `applicationServerKey` value is required.
- Derived by browser-compat-data mirroring from Chrome Android.
- No WebView Android support is recorded in browser-compat-data.
- WebKit's Safari 18.4 post: "Declarative Web Push is now available on iOS and iPadOS 18.4 for web apps added to the Home Screen." It describes Declarative Web Push as push notifications that can display without requiring a service worker.
- browser-compat-data has no Declarative Web Push entry. Its nearest key, `api.Window.pushManager`, records Safari on iOS 18.4 and is marked experimental.
- OpenPWA device test, 2026-10-20, iPhone 16 Pro, iOS 18.6.2 (22G100): `window.pushManager` is also exposed in a plain Safari tab; in a Home Screen app whose service worker is scoped to a subpath, `window.pushManager.getSubscription()` returned `null` while the worker's registration held a subscription, consistent with WebKit's statement that only a root-scoped worker shares the window's subscription.
Ecosystem & commercial policy
| Entity | Type | Context | Status | Sponsored | Notes |
|---|---|---|---|---|---|
| Apple Push (APNs)# | delivery_policy | iOS | Partial | No | iOS Web Push requires the user to add the app to the Home Screen first. |
Try it
Run this capability in the OpenPWA demo app: /demo/#push