Apple started suporting push notifications on iOS and iPadOS 16.4+ for web apps added to a user’s home screen. This functionality works across Safari, Chrome, and Edge browsers, opening new engagement opportunities for web-first companies. This comprehensive guide covers everything you need to implement iOS web push notifications successfully.

Example web push notification on mobile.

​
Important updates for 2025

Cross-Browser Support: Web push notifications now work across all major browsers on iOS/iPadOS 16.4+ including Safari, Chrome, and Edge. iOS 17+ Improvements: Enhanced implementation with relevant APIs enabled by default, making web push more accessible to users. Reliability Considerations: Some developers report occasional reliability issues where iOS web push notifications may work initially but then stop unexpectedly. Monitor your notification delivery rates and have fallback engagement strategies in place.

​
Requirements

  • iOS/iPadOS Version: 16.4 or higher
  • HTTPS Origin: Secure connection with responsive design
  • Web Application Manifest: Valid manifest.json file with correct settings
  • Home Screen Installation: Web app must be added to user’s home screen from any supported browser
  • User-Initiated Action: User must interact with your site before permission prompts can appear
  • OneSignal Service Worker: Required for notification delivery

​
Progressive web app (PWA) check

If your website is already a Progressive Web App (PWA), no additional site updates are needed. Use Lighthouse in Chrome DevTools to audit whether your site qualifies as a PWA.

​
Setup

​
1. Create your web application manifest

A Web Application Manifest (manifest.json) is a JSON file that defines how your web application appears and behaves when installed on a user’s device. For iOS web push, this file is mandatory.

​
Required manifest fields

Your manifest.json must include these essential fields:
  • $schema (recommended): JSON schema URL for validation and IDE support
  • name (required): Full application name displayed to users
  • display (required): Must be set to "standalone" or "fullscreen" for iOS compatibility
  • start_url (required): Entry point URL when the application launches
  • icons (required): Array of icon objects with multiple sizes
  • id (recommended): Unique identifier allowing multiple app instances

​
Example manifest file

{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "OneSignal Manifest Example",
  "short_name": "OS Manifest",
  "display": "standalone",
  "start_url": "/",
  "theme_color": "#E54B4D",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-256x256.png", "sizes": "256x256", "type": "image/png" },
    { "src": "/icon-384x384.png", "sizes": "384x384", "type": "image/png" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "id": "?homescreen=1"
}

​
Implementation steps

  1. File Placement: Place manifest.json in your website’s root directory
  2. HTML Integration: Add this link tag to the <head> section of all pages:
<link rel="manifest" href="/manifest.json"/>
  1. Icon Preparation: Create high-quality PNG icons in multiple sizes (192x192, 256x256, 384x384, 512x512 pixels recommended)
Use tools like SimiCart Manifest Generator to quickly create manifest files, or validate existing ones with Manifest Tester.

​
2. Add the OneSignal service worker

If you’ve already completed our Web SDK setup and can receive web push notifications on other browsers, this step is complete. See OneSignal Service Worker documentation for detailed setup instructions.

​
3. Configure permission prompts

Existing Web permission prompts from your Web SDK setup will work on iOS devices only after users add your site to their home screen and open it from there. This is Apple’s design requirement.

​
4. Guide users to “Add to Home Screen”

Unlike desktop or Android devices where permission prompts appear based on your settings, iOS requires a specific user journey that you must facilitate.

​
The required user journey

Users must complete these steps to receive notifications:
  1. Visit your website on Safari, Chrome, or Edge on iOS/iPadOS 16.4+
  2. Click the browser’s Share button
  3. Select Add to Home Screen option
  4. Save the app to their device
  5. Open the app from the home screen (not the browser)
  6. Interact with your subscribe button to trigger the native permission prompt

Adding a Website to the Home Screen on iOS

​
User onboarding strategies

Since this process isn’t intuitive, implement clear guidance through:
  • Website banners: Display banners specifically on mobile Apple devices explaining the value of notifications and providing step-by-step instructions.
  • Visual guides: Use screenshots and arrows to show users exactly where to tap.
  • Timing: Present the guidance after users have demonstrated engagement with your content.

​
Implementation examples

Here are effective approaches from real applications:

Example banner prompting users to add to home screen

Step-by-step visual guidance

Benefits-focused messaging

Clear call-to-action with visual cues

​
Open source solutions

Consider implementing this popular open-source banner solution: GitHub Project: add-to-home-screen by rajatsehgal

Example of an Add to Home Screen banner prompt from an open source project by rajatsehgal.

Additional banner examples and best practices available at web.dev.

​
5. Testing and validation

​
Manifest file testing

  1. Accessibility Check: Navigate to https://yoursite.com/manifest.json to ensure public accessibility
  2. Browser DevTools:
    • Open Chrome DevTools (F12)
    • Go to Application tab → Manifest
    • Review any errors or warnings
  3. Online Validators:

​
End-to-end push notification testing

  1. Visit your website on iOS 16.4+ device using Safari, Chrome, or Edge
  2. Click the browser’s Share button
  3. Select Add to home screen
  4. Save the app to your device
  5. Open the app from the home screen (crucial step)
  6. Trigger your subscribe button - the native permission prompt should appear
  7. Grant permission and test notification delivery

​
Important testing notes

Re-testing requirements: To test again on the same device:
  • Remove the app from home screen
  • Clear browser cache (Settings > Safari/Chrome/Edge > Clear cache)
  • Repeat the process
Permission denied recovery: If permission is denied, the home screen app must be removed and re-added for the permission prompt to appear again. Common issues to check:
  • Ensure display field is "standalone" or "fullscreen"
  • Verify all icon paths are accessible
  • Confirm manifest serves with correct MIME type (application/manifest+json)
  • Test for CORS errors

​
Troubleshooting

Manifest not loading: Check file path, HTTPS requirement, and MIME type configuration on your server. Icons not displaying: Verify icon file accessibility and correct size specifications in manifest. Permission prompt not appearing: Ensure user accessed site via home screen app and clicked an interactive element first. Notifications not delivering: Verify OneSignal service worker is properly installed and check browser console for errors.

​
Next steps

You’re now ready to send notifications! Continue to Push documentation or use our Create message API to start engaging your iOS users with web push notifications.
For ongoing success, monitor your iOS web push performance metrics and consider implementing progressive enhancement strategies that gracefully handle the additional steps required for iOS users while providing seamless experiences on other platforms.