Install first; ask for permission later
- Add the site to the Home Screen.
- Open it as a web app.
- Use an in-context control to request permission.
- Manage notifications through iOS or iPadOS settings and Focus.
That sequence is the product experience to design and test. Treat installation and notification consent as separate decisions.
Design the installation and permission steps as separate decisions
Adding a site to the Home Screen does not itself grant notification permission. Explain why installation is useful without implying that it subscribes the person. After the web app opens from its Home Screen icon, provide a visible control tied to a concrete alert, such as “Notify me when this order ships.” That interaction can lead to the native permission request.
Do not trigger the native request on first launch. Apple’s published Web Push guidance requires the request to be in response to direct user interaction. Apply the same explanation and denial-recovery principles from the Web Push permission-prompt guide.
Understand the evolving Home Screen behavior
Apple introduced standards-based Web Push for Home Screen web apps in iOS and iPadOS 16.4. Its original guidance described a manifest configured for standalone or fullscreen display. WebKit later explained that iOS 26 and iPadOS 26 can open any site added to the Home Screen as a web app by default, while still using manifest data when supplied. Because installed behavior evolves, keep a valid Web App Manifest for identity, icons, start URL, and display intent, but verify the current operating-system flow rather than relying on an old screenshot.
Use a manifest that gives the installed app a stable identity
{
"name": "Example alerts",
"short_name": "Alerts",
"id": "/",
"start_url": "/alerts",
"display": "standalone",
"icons": [
{"src": "/icon-192.png", "sizes": "192x192", "type": "image/png"},
{"src": "/icon-512.png", "sizes": "512x512", "type": "image/png"}
]
}
The exact values should reflect the site. A stable manifest id helps identify the web app, while appropriate icons prevent an improvised fallback. Keep the start URL inside the service-worker scope used for push.
Test the Apple-device journey in order
- Serve the site and manifest over HTTPS and confirm the icon and name.
- Add the site to the Home Screen using the current browser share flow.
- Launch from the Home Screen icon rather than continuing in the browser tab.
- Use the site’s explicit subscribe action and inspect the permission result.
- Store the resulting subscription with its endpoint and key material.
- Send a test notification while the web app is backgrounded and while the device is locked.
- Tap the notification and confirm the click focuses or opens the intended in-scope URL.
Account for Focus and per-app settings
A successful send does not guarantee an immediate alert. The person can configure notification presentation, silence the web app, or use Focus modes. WebKit states that Home Screen web-app notifications integrate with Focus, and settings can synchronize for the same web app identity across devices. Treat those controls as user authority, not delivery defects your site should bypass.
If a subscriber reports missing alerts, ask them to verify the installed web app’s notification settings and Focus state after you confirm the endpoint is valid and the push service accepted the request.
Do not confuse standards-based Web Push with native APNs integration
If the Home Screen requirement changes the product decision, ask whether this Web Push service fits your site before designing an Apple-only workaround.
Apple devices use Apple infrastructure underneath, but a website implements the standard Push API, Notifications API, and service-worker flow. Apple’s guidance says a Web Push implementation does not require Apple Developer Program membership. Your server sends to the endpoint supplied by the browser rather than registering the web app as a native iOS application.
This distinction matters when debugging. VAPID, Web Push encryption, and the browser-issued endpoint remain part of the website flow. The Web Push, APNs, and FCM comparison shows where native-app device tokens and app entitlements belong instead.
Use feature detection and current Apple guidance
Do not hard-code a rule that every Apple mobile browser behaves identically forever. Confirm the site is running in the expected installed context and detect the required APIs. Third-party browsers can participate in adding sites to the Home Screen, but the resulting web app and operating-system behavior should be tested on the versions you support.
Read WebKit’s official guides for Web Push on iOS and iPadOS and the later Safari 26 Home Screen changes. The W3C Push API remains the standards boundary for subscriptions and push events.
If the visitor is not using an installed web app, explain the installation step and offer another channel for the requested event. If the installed flow still fails, follow the Web Push debugging sequence rather than showing a broken subscribe button.