Skip to content

Concept in Notifications

Web Push on iOS and iPadOS (16.4+)

Published Updated

Available in all core browsersW3C

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.

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.

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.

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.

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).

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.

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).

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.

Specifications

SpecificationStatus
Web PushW3C
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes42highsource1
Chrome (Android)#Yes42highsource23
Edge (Desktop)#Yes17highsource4
Firefox (Desktop)#Yes44highsource5
Firefox (Android)#Yes48highsource6
Safari (macOS)#Yes16highsource7
Safari (iOS)#Yes16.4highsource8
Samsung Internet#Yes4.0highsource910
WebView (Android)#No—highsource11
Safari (iOS) · Declarative Web Push#Yes18.4mediumsource121314
  1. The `options` parameter with a `applicationServerKey` value is required.
  2. The `options` parameter with a `applicationServerKey` value is required.
  3. Derived by browser-compat-data mirroring from Chrome.
  4. The `options` parameter with a `applicationServerKey` value is required.
  5. From Firefox 72 onwards, can only be called in response to a user gesture such as a `click` event.
  6. From Firefox Android 79 onwards, can only be called in response to a user gesture such as a `click` event.
  7. Notifications are supported on macOS Ventura and later.
  8. Notifications are supported in web apps saved to the home screen.
  9. The `options` parameter with a `applicationServerKey` value is required.
  10. Derived by browser-compat-data mirroring from Chrome Android.
  11. No WebView Android support is recorded in browser-compat-data.
  12. 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.
  13. 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.
  14. 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

EntityTypeContextStatusSponsoredNotes
Apple Push (APNs)#delivery_policyiOSPartialNoiOS Web Push requires the user to add the app to the Home Screen first.

Source data: /compatibility/web-push.json · Global usage: 96 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-20 · Confidence: medium (computed from sources)