Web push on iPhone: iOS 16.4 requirements and how to guide users

Yes, you can send web notifications to an iPhone, but only on iOS 16.4 or later and only after the user has added your site to the Home Screen and opened it from that icon. In a regular Safari tab the notifications API doesn't even exist, so your job is to detect that case and explain installation in a few clear steps.

In short:

• You need iOS or iPadOS 16.4 or later, and the site must be opened from its Home Screen icon.
• From iOS 16.4 through iOS 18, the site needs a manifest with display set to standalone or fullscreen; since iOS 26 any site added to the Home Screen opens as an app, but a manifest is still recommended.
• In a Safari tab, Notification and PushManager don't exist: if you only check for support, you'll hide the button from every iPhone user.
• Permission is requested inside the installed site, always from a user tap.
• iOS has no automatic install prompt, so the explaining is up to you.

The requirements, one by one

Apple laid out the conditions when it announced web push for web apps on iOS and iPadOS. In summary:

You don't need an Apple Developer account or certificates: it's the same standard Web Push with VAPID keys you use for Chrome or Firefox, with endpoints on web.push.apple.com. If your server filters which endpoint domains it accepts, allow any subdomain of push.apple.com. Once subscribed, users get notifications just like a native app's: on the Lock Screen, in Notification Center and on a paired Apple Watch, following their Focus settings.

Why Safari never shows the prompt

The most common failure isn't technical, it's a design choice. Many sites show their notification button like this:

if ('Notification' in window && 'PushManager' in window) {
  showNotifyButton();
}

In a Safari tab on iPhone, window.Notification doesn't exist, the check fails and the button never appears. Users don't know your site can notify them, and you lose that channel with every iPhone visitor. Instead of hiding the feature, handle three cases: the browser supports push (show the button), it's an iPhone or iPad that hasn't installed the site (show install steps), or there's no support (show nothing):

const ua = navigator.userAgent;
const isIOS = /iPhone|iPad|iPod/.test(ua) ||
  (/Macintosh/.test(ua) && navigator.maxTouchPoints > 1); // iPadOS reports itself as a Mac
const isInstalled = window.matchMedia('(display-mode: standalone)').matches ||
  navigator.standalone === true;

if (isIOS && !isInstalled) showInstallSteps();
else if ('PushManager' in window) showNotifyButton();

If you use castly, Castly.needsInstall() runs this check for you: it returns true in Safari on iPhone or iPad when the site isn't installed.

The minimal manifest

Serve a manifest file and link it from the <head> of every page:

{
  "name": "Example Store",
  "short_name": "Store",
  "id": "/",
  "start_url": "/",
  "display": "standalone",
  "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="/apple-touch-icon.png">

The field that matters is display. Without standalone or fullscreen, iOS 16.4 through 18 saves the site as a plain bookmark that opens in Safari, and there's no push there. iOS 26 changed the default: any site added to the Home Screen opens as an app even without a manifest, unless the user turns that option off while adding it. Keep the manifest anyway: people on older versions still need it, and it sets the name, icon and start URL. The id field identifies the installed app, and iOS uses it together with the name to sync Focus settings across devices.

How to guide users through installation

Since iOS won't offer installation on its own, the explanation is on you. Show it once the user has asked for alerts, for example after tapping "Notify me when my order ships", not on page load. Three steps are enough:

1. Tap Safari's Share button, the square with an arrow pointing up. In some versions it sits inside the "…" menu.
2. Choose "Add to Home Screen" and confirm with "Add".
3. Open the site from the new icon and tap "Turn on notifications" again.

A few details make a real difference:

• Lead with the benefit in one sentence: "Install the site to get delivery updates on your iPhone."
• Use the exact words users will see on screen and, if you can, an arrow pointing at Safari's toolbar.
• Let users dismiss the explanation and don't repeat it on every visit: save the date in localStorage and wait a few days.
• Since iOS 16.4, other browsers can offer "Add to Home Screen" in their own share menu if they implement it; if you detect one of them, adjust the copy.

After installing: permission inside the app

When the user opens the site from its icon, they're in a fresh context. Keep three things in mind:

• The session may not carry over. The installed site usually gets its own storage, separate from Safari's, so don't assume the user is still signed in. If you link subscriptions to users, ask them to sign in before subscribing, or attach the subscription when they do.
• Permission needs a tap. Request it directly in the click handler. If you chain slow requests before it, the browser may no longer treat it as a user action.
• If they say no, the way back is in Settings. iOS shows its system dialog, and if the user declines, they can only turn it back on in Settings > Notifications > (your site's name). Detect the denied state and explain that instead of insisting.

button.addEventListener('click', async () => {
  const permission = await Notification.requestPermission();
  if (permission === 'granted') await subscribeAndSave(); // pushManager.subscribe() + POST to your API
  else if (permission === 'denied') showSettingsHelp();
});

The timing and wording of that request matter as much as on desktop; we dig into both in when to ask for notification permission.

How to test on a real iPhone

1. Deploy the site to a domain with valid HTTPS. The iPhone can't reach your computer's localhost, so use a staging environment or a tunnel.
2. Add it to the Home Screen, open it from the icon and subscribe.
3. Send a test push and lock the phone: it should show up on the Lock Screen. If it doesn't, check that no Focus mode is active.
4. To debug the service worker, turn on Settings > Safari > Advanced > Web Inspector, connect the iPhone to a Mac with a cable and use Safari's Develop menu on the Mac. The worker code itself is the same as anywhere else; see your first service worker for push.

Each installation creates its own subscription. If the user deletes the icon and installs the site again, you'll get a new endpoint and the old one will normally stop working, so your server should remove subscriptions that answer 404 or 410. In the castly dashboard's Playground you can subscribe your own iPhone as a test device and send it a push; the quickstart covers the full integration.

Frequently asked questions

Does web push work in Chrome or Firefox for iPhone?

Not in a regular tab: iOS browsers built on WebKit, which is practically all of them, don't offer web push inside the browser. Since iOS 16.4 they can add sites to the Home Screen if they implement that option, and the installed site gets push just as if it had been added from Safari.

Does it work in the European Union?

Yes. In 2024 Apple announced it would drop Home Screen web apps in the EU with iOS 17.4, but it reversed course before the final release and kept them, push included. Everything works the same as in the rest of the world.

Can I show a number on the installed app's icon?

Yes. Since iOS 16.4, Home Screen web apps support the Badging API: call navigator.setAppBadge(3) from the page or while handling a push in the service worker, and navigator.clearAppBadge() to remove it. The badge only shows once the user has allowed notifications.

Can I show an automatic install prompt like on Android?

No. iOS doesn't fire beforeinstallprompt and doesn't let you install the site from JavaScript. All you can do is detect that the user is in Safari without the site installed and show them the steps.

What about Safari on the Mac?

macOS is different: Safari supports web push in regular tabs since macOS 13 Ventura, with nothing to install. The same subscription and sending code you use for Chrome and Firefox works there too.