Web push FAQ
Complete guide to OneSignal Web Push Notifications setup, requirements, browser compatibility, domain changes, and troubleshooting common issues for developers and website owners.
Web push requirements
Your website must meet all of the following for Web Push to work:
Browser APIs required
Security & connection
- ✅ HTTPS only (with valid SSL certificate)
- ✅ OneSignal’s service worker installed
- ✅ Browser must reach:
- Browser push servers (e.g., FCM, Mozilla)
api.onesignal.com
User state
- ✅ Notification permission granted by user
- ❌ Not in Incognito/Private/Guest mode
- ❌ Site data not cleared (deletes subscriptions)
iOS/iPadOS requirements
To receive push on iOS or iPadOS:
- iOS 16.4+ or iPadOS 16.4+
- Site must be added to home screen and opened from there
- Valid
manifest.jsonfile with required fields - Users must accept notification permissions after opening as web app
iOS web push setup
Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
Browser & platform support
Browser compatibility by operating system
| Browser | Windows PC | macOS | Android | iOS (iPhone, iPad) |
|---|---|---|---|---|
| Chrome | Yes | Yes | Yes | No |
| Firefox | Yes | Yes | Yes | No |
| Safari | No | Yes | No | Yes ¹ |
| Microsoft Edge ² | Yes | Yes | Yes | No |
| Opera ² | Yes | Yes | Yes | No |
| Samsung Internet ² | No | No | Yes | No |
| Yandex ² | Yes | Yes | Yes | No |
| UC Browser ² | Yes | No | Yes | No |
| Internet Explorer ³ | No | No | No | No |
| DuckDuckGo | No | No | No | No |
- ¹ iOS Safari requires web app installation (see requirements above)
- ² Chromium-based browsers appear as “Chrome” in OneSignal analytics
- ³ Internet Explorer is deprecated and no longer receives updates
Minimum browser versions
| Browser | Minimum Version Required |
|---|---|
| Google Chrome | Chrome 50+ |
| Mozilla Firefox | Firefox 47+ |
| Apple Safari | Safari 10+ (macOS), Safari 16.4+ (iOS/iPadOS 16.4+) |
Domain changes & migration
Understanding browser origin policy
Browsers tie web push subscriptions to a specific origin (domain/site URL) for security reasons. You cannot transfer subscribers between different origins - this is a browser limitation, not a OneSignal restriction.
Different origins include:
- HTTP vs HTTPS (e.g.,
http://mysite.com→https://mysite.com) - www vs non-www (e.g.,
www.mysite.comvsmysite.com) - Different domains/subdomains (e.g.,
domain1.comvsdomain2.comorsub1.domain.comvssub2.domain.com)
Migration options
When changing your site’s origin, choose one of these approaches:
Best for: Most domain changes, especially when you want a clean migration
- Create new OneSignal App for your new domain
- Dual-send strategy: Continue sending from old app, but set “Launch URL” to your new domain
- Gradual transition:
- High-frequency senders (1+ notifications/day): 2 weeks transition
- Medium-frequency senders (2+ notifications/week): 2 months transition
- Migration notifications: Send 1-2 messages like “We’ve moved! Visit our new site to stay updated” at the beginning and end of transition
Best for: Most domain changes, especially when you want a clean migration
- Create new OneSignal App for your new domain
- Dual-send strategy: Continue sending from old app, but set “Launch URL” to your new domain
- Gradual transition:
- High-frequency senders (1+ notifications/day): 2 weeks transition
- Medium-frequency senders (2+ notifications/week): 2 months transition
- Migration notifications: Send 1-2 messages like “We’ve moved! Visit our new site to stay updated” at the beginning and end of transition
Best for: When you need to keep the same OneSignal App ID
-
Use Update an app API with:
name: Your app/site namechrome_web_origin: New site URLchrome_web_default_notification_icon: Icon image URL
-
Delete old subscribers to prevent duplicates:
- Create segment: “Device Type is Web Push”
- Delete all users in segment
HTTP to HTTPS upgrade
Upgrading from HTTP to HTTPS creates a new origin. Follow the domain migration steps above since browsers treat HTTPS sites as completely separate from their HTTP versions.
Multiple sites & subdomains
Single app limitations
Due to browser same-origin policy, you cannot use one OneSignal App for multiple origins like:
https://mysite.comandhttps://www.mysite.comhttps://main.comandhttps://shop.main.com
Solutions for multiple origins
- Subscribe users only on your main domain
- Redirect users from other origins to main domain for subscription
- Redirect back to original page after subscription
- Subscribe users only on your main domain
- Redirect users from other origins to main domain for subscription
- Redirect back to original page after subscription
- Create individual OneSignal Apps for each origin
- Accept that users may receive duplicate notifications if subscribed to multiple sites
Language support scenarios
- URLs like
https://mysite.com/en/orhttps://mysite.com/es/ - Use single OneSignal App
- Follow multi-language prompts guide
- Implement Language & Localization
- URLs like
https://mysite.com/en/orhttps://mysite.com/es/ - Use single OneSignal App
- Follow multi-language prompts guide
- Implement Language & Localization
- URLs like
https://en.mysite.comorhttps://es.mysite.com - Requires separate OneSignal Apps for each subdomain
Advanced configuration
Multiple OneSignal apps on same site
- Not recommended - causes subscription conflicts.
- What happens: OneSignal auto-resubscribes users to the most recently visited App ID, causing subscribers to bounce between apps and creating many unsubscribed devices.
- Better approach: Use Data Tags to segment users within a single app.
Subfolder sites
Web push operates at the origin level. For sites in subfolders (e.g., https://example.com/blog), use the main origin (https://example.com) for setup.
Special case: If you must place service workers in the subfolder, see Customizing Service Worker Integration.
Self-hosting SDK files
Strongly discouraged. Browser push specifications change frequently, and OneSignal updates files immediately to maintain compatibility. Use OneSignal’s CDN URLs from your Web Push Settings instead.
Custom init code
Custom init code only works with Custom Code Setup.
Typical Setup or Website Builder users: Custom init code will be ignored by the OneSignal SDK.
If you need to delay initialization, use the privacy methods.
Development & testing
Local environment testing
See Web SDK setup > Local testing for complete local testing setup.
Service worker integration
OneSignal can work alongside existing service workers and PWAs. See Integrating Multiple Service Workers for implementation details.
Troubleshooting
Update deployment timing
- Service Worker files: 24-hour cache
- Web SDK: 3-day cache
Plan accordingly when deploying critical updates.
macOS Chrome notification issues
For macOS Chrome users, ensure notifications are enabled for both:
- Google Chrome app (Apple Menu > Settings > Notifications)
- Google Chrome Helper app
Without both enabled, notifications won’t appear in the notification center.
Next steps after setup
- Test thoroughly across your supported browsers and devices
- Implement proper error handling for permission requests
- Set up analytics to monitor subscription rates
- Plan your notification strategy to avoid user fatigue
- Consider A/B testing your permission request timing and messaging
Common migration gotchas
- Browser data clearing unsubscribes users automatically
- Duplicate notifications during dual-app transitions
- iOS requires web app installation before push works
- Private/Incognito modes never support push notifications
- Service workers must be accessible at your site’s root or configured subdirectory
Next steps
Web push FAQ
Complete guide to OneSignal Web Push Notifications setup, requirements, browser compatibility, domain changes, and troubleshooting common issues for developers and website owners.
Web push requirements
Your website must meet all of the following for Web Push to work:
Browser APIs required
Security & connection
- ✅ HTTPS only (with valid SSL certificate)
- ✅ OneSignal’s service worker installed
- ✅ Browser must reach:
- Browser push servers (e.g., FCM, Mozilla)
api.onesignal.com
User state
- ✅ Notification permission granted by user
- ❌ Not in Incognito/Private/Guest mode
- ❌ Site data not cleared (deletes subscriptions)
iOS/iPadOS requirements
To receive push on iOS or iPadOS:
- iOS 16.4+ or iPadOS 16.4+
- Site must be added to home screen and opened from there
- Valid
manifest.jsonfile with required fields - Users must accept notification permissions after opening as web app
iOS web push setup
Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
Browser & platform support
Browser compatibility by operating system
| Browser | Windows PC | macOS | Android | iOS (iPhone, iPad) |
|---|---|---|---|---|
| Chrome | Yes | Yes | Yes | No |
| Firefox | Yes | Yes | Yes | No |
| Safari | No | Yes | No | Yes ¹ |
| Microsoft Edge ² | Yes | Yes | Yes | No |
| Opera ² | Yes | Yes | Yes | No |
| Samsung Internet ² | No | No | Yes | No |
| Yandex ² | Yes | Yes | Yes | No |
| UC Browser ² | Yes | No | Yes | No |
| Internet Explorer ³ | No | No | No | No |
| DuckDuckGo | No | No | No | No |
- ¹ iOS Safari requires web app installation (see requirements above)
- ² Chromium-based browsers appear as “Chrome” in OneSignal analytics
- ³ Internet Explorer is deprecated and no longer receives updates
Minimum browser versions
| Browser | Minimum Version Required |
|---|---|
| Google Chrome | Chrome 50+ |
| Mozilla Firefox | Firefox 47+ |
| Apple Safari | Safari 10+ (macOS), Safari 16.4+ (iOS/iPadOS 16.4+) |
Domain changes & migration
Understanding browser origin policy
Browsers tie web push subscriptions to a specific origin (domain/site URL) for security reasons. You cannot transfer subscribers between different origins - this is a browser limitation, not a OneSignal restriction.
Different origins include:
- HTTP vs HTTPS (e.g.,
http://mysite.com→https://mysite.com) - www vs non-www (e.g.,
www.mysite.comvsmysite.com) - Different domains/subdomains (e.g.,
domain1.comvsdomain2.comorsub1.domain.comvssub2.domain.com)
Migration options
When changing your site’s origin, choose one of these approaches:
Best for: Most domain changes, especially when you want a clean migration
- Create new OneSignal App for your new domain
- Dual-send strategy: Continue sending from old app, but set “Launch URL” to your new domain
- Gradual transition:
- High-frequency senders (1+ notifications/day): 2 weeks transition
- Medium-frequency senders (2+ notifications/week): 2 months transition
- Migration notifications: Send 1-2 messages like “We’ve moved! Visit our new site to stay updated” at the beginning and end of transition
Best for: Most domain changes, especially when you want a clean migration
- Create new OneSignal App for your new domain
- Dual-send strategy: Continue sending from old app, but set “Launch URL” to your new domain
- Gradual transition:
- High-frequency senders (1+ notifications/day): 2 weeks transition
- Medium-frequency senders (2+ notifications/week): 2 months transition
- Migration notifications: Send 1-2 messages like “We’ve moved! Visit our new site to stay updated” at the beginning and end of transition
Best for: When you need to keep the same OneSignal App ID
-
Use Update an app API with:
name: Your app/site namechrome_web_origin: New site URLchrome_web_default_notification_icon: Icon image URL
-
Delete old subscribers to prevent duplicates:
- Create segment: “Device Type is Web Push”
- Delete all users in segment
HTTP to HTTPS upgrade
Upgrading from HTTP to HTTPS creates a new origin. Follow the domain migration steps above since browsers treat HTTPS sites as completely separate from their HTTP versions.
Multiple sites & subdomains
Single app limitations
Due to browser same-origin policy, you cannot use one OneSignal App for multiple origins like:
https://mysite.comandhttps://www.mysite.comhttps://main.comandhttps://shop.main.com
Solutions for multiple origins
- Subscribe users only on your main domain
- Redirect users from other origins to main domain for subscription
- Redirect back to original page after subscription
- Subscribe users only on your main domain
- Redirect users from other origins to main domain for subscription
- Redirect back to original page after subscription
- Create individual OneSignal Apps for each origin
- Accept that users may receive duplicate notifications if subscribed to multiple sites
Language support scenarios
- URLs like
https://mysite.com/en/orhttps://mysite.com/es/ - Use single OneSignal App
- Follow multi-language prompts guide
- Implement Language & Localization
- URLs like
https://mysite.com/en/orhttps://mysite.com/es/ - Use single OneSignal App
- Follow multi-language prompts guide
- Implement Language & Localization
- URLs like
https://en.mysite.comorhttps://es.mysite.com - Requires separate OneSignal Apps for each subdomain
Advanced configuration
Multiple OneSignal apps on same site
- Not recommended - causes subscription conflicts.
- What happens: OneSignal auto-resubscribes users to the most recently visited App ID, causing subscribers to bounce between apps and creating many unsubscribed devices.
- Better approach: Use Data Tags to segment users within a single app.
Subfolder sites
Web push operates at the origin level. For sites in subfolders (e.g., https://example.com/blog), use the main origin (https://example.com) for setup.
Special case: If you must place service workers in the subfolder, see Customizing Service Worker Integration.
Self-hosting SDK files
Strongly discouraged. Browser push specifications change frequently, and OneSignal updates files immediately to maintain compatibility. Use OneSignal’s CDN URLs from your Web Push Settings instead.
Custom init code
Custom init code only works with Custom Code Setup.
Typical Setup or Website Builder users: Custom init code will be ignored by the OneSignal SDK.
If you need to delay initialization, use the privacy methods.
Development & testing
Local environment testing
See Web SDK setup > Local testing for complete local testing setup.
Service worker integration
OneSignal can work alongside existing service workers and PWAs. See Integrating Multiple Service Workers for implementation details.
Troubleshooting
Update deployment timing
- Service Worker files: 24-hour cache
- Web SDK: 3-day cache
Plan accordingly when deploying critical updates.
macOS Chrome notification issues
For macOS Chrome users, ensure notifications are enabled for both:
- Google Chrome app (Apple Menu > Settings > Notifications)
- Google Chrome Helper app
Without both enabled, notifications won’t appear in the notification center.
Next steps after setup
- Test thoroughly across your supported browsers and devices
- Implement proper error handling for permission requests
- Set up analytics to monitor subscription rates
- Plan your notification strategy to avoid user fatigue
- Consider A/B testing your permission request timing and messaging
Common migration gotchas
- Browser data clearing unsubscribes users automatically
- Duplicate notifications during dual-app transitions
- iOS requires web app installation before push works
- Private/Incognito modes never support push notifications
- Service workers must be accessible at your site’s root or configured subdirectory