Send web push to iPhone and iPad from a Home Screen web app. Confirm your web app manifest, have visitors add your site to the Home Screen, and request permission from that icon.
Send web push to iPhone and iPad from a Home Screen web app. iOS and iPadOS 16.4 and later show the notification permission prompt only after a visitor opens that icon and taps a subscribe button. A tab in Safari, Chrome, Edge, or Firefox cannot request permission.Finish web push setup first so the OneSignal Web SDK and service worker are already on your site. WordPress and Shopify install those for you. Keep the web app manifest you already serve, and confirm it includes the fields on this page. Add a manifest only if the site does not have one. You still add the Home Screen instructions.
Web push notification from a Home Screen web app on iPhone.
Meet every item below before you test on a device:
iOS 16.4 or later, or iPadOS 16.4 or later
Your site served over HTTPS
The OneSignal Web SDK and service worker installed on that origin
A visitor who adds your site to the Home Screen and opens the new icon
A subscribe button the visitor taps inside that web app
iOS delivers these notifications through APNs using standard Web Push (VAPID, the Push API, and a service worker). OneSignal handles VAPID for you.
A Home Screen bookmark opens your site in the browser. Bookmarks cannot request notification permission. The icon has to open as a web app, with its own entry in the App Switcher and no browser toolbar.
On iOS 16.4 through 18 and iPadOS 16.4 through 18, the icon opens as a web app only when your manifest sets display to standalone or fullscreen. The legacy <meta name="apple-mobile-web-app-capable" content="yes"> tag also requests that behavior. browser and minimal-ui save a bookmark that opens in the default browser. Which browser the visitor used to add the site does not matter.On iOS 26 and iPadOS 26 and later, every site added to the Home Screen opens as a web app by default. The add sheet includes an Open as Web App switch, and that switch is on. If the visitor turns it off, iOS saves a bookmark instead, even when your manifest asks for standalone. Keep the manifest anyway: iOS 16.4 through 18 still need display: "standalone", and on every version the manifest supplies the name, icons, and start URL.There is no install button and no beforeinstallprompt event on iOS. Tell visitors to use the Share sheet.
A web app manifest is the JSON file that tells the operating system the name, icon, and start URL of your Home Screen web app. Keep the file your site already serves, on the same origin. https://yoursite.com/manifest.json is the usual location. Match these fields in that file. Add a manifest only if the site does not have one:
standalone. On iOS 16.4 through 18, fullscreen also opens a web app. browser and minimal-ui save a bookmark on those versions.
name
Default label on the Home Screen. Visitors can edit it while adding the site. Settings > Notifications uses the name they save.
short_name
A shorter label under the icon when name does not fit.
start_url
The path that opens when the visitor taps the icon. Keep it on the same origin.
scope
Paths that stay inside the web app. Links outside scope open in the browser. If you omit scope, it defaults to the directory of start_url.
id
Optional. Identity for this Home Screen web app. If absent, the browser uses start_url. If present, keep it stable.
icons
PNG files at 192×192 and 512×512. Set purpose to any, or omit purpose. An icon marked only maskable can be ignored on iOS.
iOS 16.4 through 18 reads display. Setting display_override to standalone and leaving display as browser still saves a bookmark on those versions. Icon src values resolve against the manifest URL, so use root-relative paths such as /icons/icon-192.png. The file must be valid JSON: no comments and no trailing commas.Serve the file with Content-Type: application/manifest+json. In the <head>, keep one <link rel="manifest">, pointed at the file you already serve. Browsers use the first manifest link on the page.
Add the apple-touch-icon link if it is missing, using a 180×180 PNG. When that link is absent, iOS falls back to a manifest icon whose purpose is any or omitted. PNG covers iOS 16.4 and later. Safari 26 and later also accepts SVG, so keep a PNG for older versions.
Leave id unchanged after visitors add the site. If the manifest has no id, leave it out. The browser uses start_url as the identity, and a new id is a different Home Screen web app, with a new permission prompt and a new push subscription.
Confirm the file before you test on a phone:
Open the manifest URL and confirm the JSON loads with HTTP 200. A redirect to another host, including www and non-www, is a different origin.
In desktop Chrome, open DevTools, go to Application > Manifest, and confirm there are no errors, the manifest identity matches the file you edited, and display is standalone or fullscreen.
Open each icon URL and confirm it returns the image.
View the page source and confirm there is one <link rel="manifest">.
2
Confirm the OneSignal service worker
If web push already works on desktop or Android, this step is done. The same OneSignalSDKWorker.js file receives iOS web push. See OneSignal service worker if you still need to add it.If the site already has a service worker, keep that file. Only one service worker can control a scope, so a second file at / replaces the existing one. Follow Combining multiple service workers instead of adding another worker at the root.OneSignal shows the notification from that service worker when a push arrives. Safari revokes notification permission for the site if a push arrives and the service worker does not display a notification. Keep the OneSignal service worker as the handler for the push event.
3
Request permission from a tap
Your existing permission prompt works inside the Home Screen web app. The visitor taps the slide prompt, bell, or your own subscribe button, and iOS then shows the system permission dialog.Call that subscribe action from the tap. A request that runs on page load, or after a timer, is not a user gesture, and iOS does not show the dialog. From the tap handler, call OneSignal.Slidedown.promptPush() or OneSignal.Notifications.requestPermission(). Calling Notification.requestPermission() yourself skips the OneSignal subscription.In an iOS browser tab, window.Notification is undefined, so isPushSupported() returns false. That result is expected and means the tab cannot prompt yet. Show Add to Home Screen instructions anyway. After the visitor opens the Home Screen icon, isPushSupported() can return true. Show the subscribe button when the page is the Home Screen web app:
When isHomeScreenWebApp is true, show the subscribe button. When it is false, show the Add to Home Screen instructions instead.On desktop and Android, keep your normal permission prompt. Show the Home Screen instructions only on iPhone and iPad. iPadOS can report a desktop Safari user agent, so when you detect the platform, treat a Mac that reports touch support as an iPad.
4
Ask visitors to add your site to the Home Screen
Visitors subscribe only after they finish this path:
Open your site in Safari, Chrome, Edge, or Firefox on the device.
Tap Share.
Tap Add to Home Screen.
On iOS 26 and iPadOS 26 and later, leave Open as Web App on. It is on by default.
Tap Add. Visitors can edit the name on this sheet. That name is what they later see in Settings > Notifications.
Open the new Home Screen icon.
Tap your subscribe button, then tap Allow on the system prompt.
Share sheet path for Add to Home Screen on iPhone.
Show these steps in a banner on iPhone and iPad, after the visitor has used the site, while they are still in the browser. Explain what they get from notifications, then show where Share and Add to Home Screen are.
Banner that asks the visitor to add the site to the Home Screen.
Instructions that point at Share and Add to Home Screen.
Banner that leads with the benefit of notifications.
Subscribe call to action with arrows toward the Share control.
One implementation of that banner is the open-source add-to-home-screen project:
Add to Home Screen banner from the add-to-home-screen project.
5
Test on an iPhone or iPad
Use a normal browsing tab on a device running iOS 16.4 or later, or iPadOS 16.4 or later. Private Browsing can hide Add to Home Screen. Add the site from the same origin as the OneSignal Site URL, including https and www. An icon for https://www.yoursite.com does not subscribe https://yoursite.com.If you changed display after an icon was already on the Home Screen, remove that icon and add the site again. The existing icon keeps the mode it had when the visitor added it.
Open the site in Safari, Chrome, Edge, or Firefox.
Tap Share, then Add to Home Screen. On iOS 26 or later, leave Open as Web App on.
Open the icon from the Home Screen.
Tap the subscribe button. The system permission prompt appears.
Tap Allow.
Send a test notification from the OneSignal dashboard. The notification is delivered to that Home Screen web app.
The new subscriber is a web push subscription, alongside Chrome, Safari, and Firefox subscribers. They do not appear as an Apple iOS mobile-app subscription.To run the test again on the same device, remove the Home Screen icon, then add the site again. Removing the icon deletes that web app’s website data and its push subscription. The Home Screen web app stores its data separately from Safari, so clearing Safari history and website data leaves the web app subscription in place.If the visitor taps Don’t Allow, iOS does not show the system prompt again for that web app. Remove the icon, add the site again, open the icon, and tap the subscribe button.
Can visitors subscribe from a Safari tab on iPhone?
No. iOS shows the notification permission prompt only after the visitor opens your Home Screen icon and taps a subscribe button. The same limit applies to Chrome, Edge, and Firefox on iPhone and iPad.
Yes, if any visitors are on iOS 16.4 through 18. On those versions, display must be standalone or fullscreen, or the icon opens as a bookmark and web push is unavailable. On iOS 26 and iPadOS 26 and later, Add to Home Screen opens as a web app by default even without a manifest, as long as the visitor leaves Open as Web App on. Keep the manifest so the name, icons, and start URL are set on every version.
Why does isPushSupported() return false on iPhone?
In a browser tab, that result is expected. window.Notification is undefined until the visitor opens the Home Screen web app, so isPushSupported() returns false and a direct Notification.requestPermission() call throws. Show Add to Home Screen instructions in the tab. Call isPushSupported() again after the visitor opens the icon, and show the subscribe button only when it returns true.
I updated the manifest. Why is the prompt still missing?
The Home Screen icon keeps the mode it had when it was added. Remove the icon and add the site again after you change display. Then confirm the page has one <link rel="manifest">, that link points at the file you edited, and display itself is standalone or fullscreen. On iOS 16.4 through 18, display_override does not change the mode.
iOS does not show the system prompt again for that Home Screen web app. Remove the icon, add the site again, open the icon, and tap the subscribe button.After someone taps Allow, they turn notifications on or off later in Settings > Notifications, under the name they saved on the Add to Home Screen sheet.
Do I need an Apple Developer account or an APNs key?
No. iOS web push uses standard Web Push with VAPID. OneSignal manages that. An APNs .p8 key is for a native iOS app. A Safari .p12 certificate is only for the legacy macOS Website Push ID path. See Safari Web Push .p12 certificate.
Yes. Add the site from Chrome’s Share sheet, then open the Home Screen icon and tap your subscribe button. Edge and Firefox on iOS use the same path. The browser tab itself still cannot request permission.
Why did Safari turn notifications off without a settings change?
Safari revokes notification permission if a push arrives and the service worker does not display a notification. OneSignal’s service worker displays the notification for you. A custom push handler that skips displaying it can cause Safari to revoke permission.
Can I skip the service worker and use Declarative Web Push?
No. Keep the OneSignal service worker. Declarative Web Push, added in iOS 18.4 and iPadOS 18.4, lets Safari display a notification without running a service worker. OneSignal subscriptions use the service worker, which is also what delivers web push in Chrome, Edge, and Firefox.
Why did a push subscription disappear after I cleared Safari data?
Clearing Safari history and website data does not remove a Home Screen web app’s subscription. That web app keeps its own website data. Removing the Home Screen icon deletes the web app’s data and the push subscription. Add the site again and subscribe again to create a new one.
Where do iOS web push subscribers show up in OneSignal?
They show up as web push subscriptions, with your other browser subscribers. They are not Apple iOS mobile-app subscriptions, and they do not use your native APNs configuration.
