Web Push FAQ
Common questions about OneSignal's Web Push Notifications
What are the requirements for Web Push?
Push messages enable you to bring information to the attention of your users even when they're not using your website. - Chrome Developer Relations Blog
Browser requirements (use OneSignal's Browser Support by Operating System instead if it is listed there):
- Notification API
- ServiceWorker API
- Push API
- Browser cannot use Incognito / private mode
- User has to accept notification permission prompt
- Browser can connect to browser's push server, Google, Mozilla, etc.
- Browser can make API calls to onesignal.com
- Browser's site data must NOT be cleared, otherwise the push will become unsubscribed
Requirements if NOT using OneSignal Subdomain option (See FAQ: HTTP vs. HTTPS for details):
- Site is HTTPS and browser considers it secure
- Must be a registered cert or part of the system's root certificates.
- Service Worker - Add required service worker per OneSignal's setup doc
- If the site has a root Service Worker already then you must follow the Customizing Your Service Worker Integration
iOS / iPadOS Specific Requirements:
- Device is running iPadOS / iOS 16.4 or newer
- Has a manifest file, normally referred to as a manifest.json
- End-user has added the site to their home screen, opens it from there, is prompted to allow notifications, and allows notifications.
What Platforms Support Web Push Notifications?
All major browsers support Web Push. Android and iOS devices may also receive Web Push notifications in addition to notifications from apps as long as they can connect to the push gateway servers. Below is a list of platforms and browsers that support web push notifications.
Browser Support by Operating System
Incognito Mode, Private Browsing Mode, and Guest Browser Mode do not support Web Push.
Browser | Windows PC | macOS | Android | iOS (iPhone, iPad) |
---|---|---|---|---|
Chrome | Yes | Yes | Yes | Yes |
Firefox | Yes | Yes | Yes | No |
Safari | No | Yes | No | Yes |
Microsoft Edge1 | Yes | Yes | Yes | Yes |
Opera1 | Yes | Yes | Yes | No |
Samsung Internet Browser1 | No | No | Yes | No |
Yandex1 | Yes | Yes | Yes | No |
UC Browser1 | Yes | No | Yes | No |
Internet Explorer 2 | No | No | No | No |
DuckDuckGo | No | No | No | No |
Note 1: Microsoft Edge (2019 Update), Opera, Samsung Browser, Yandex, and UC Browser are all Chromium-based browsers and will be marked as Chrome in OneSignal.
Note 2: Internet Explorer is no longer receiving feature updates. Microsoft has switched browser development to the Edge platform.
Support by Browser Version
Browser | Min Version |
---|---|
Google Chrome | Chrome 50+. Chrome v42 is when web push notifications started being supported, but it uses an older payload that is no longer supported by OneSignal. More information on this here. |
Mozilla Firefox | Firefox v47+ Firefox ESR versions do not support web push notifications. Firefox v44+ is when web push notifications started being supported, but it uses an older payload that is no longer supported by OneSignal. More information on this here. If you are testing support in this browser, visit this webpage and let us know if you see any Supported: false or Errors . |
Apple Safari | Safari 10+ on macOS Safari 16.4+ on iOS and iPadOS 16.4+ |
How do I change my domain?
See Domain Management for details.
Can I setup multiple websites or subdomains with a single OneSignal App?
See Domain Management for details.
What should I do if I upgraded my site to HTTPS?
See Domain Management for details.
Can I transfer subscribers from one site to another?
See Domain Management for details.
What if my site supports multiple languages?
If your site supports multiple languages through a subdirectory like: https://mysite/com/en_us/
or https://mysite.com/other-language/
then you have the same origin (https://mysite.com
) and you can setup multiple languages on prompts following our Prompting FAQ to translate prompts and send push in different languages following Language & Localization.
If your site supports multiple languages through a subdomain like: https://en.mysite.com
, then this would be separate origins and would require multiple OneSignal Apps. Each origin will need it's own OneSignal App Id.
Can I have multiple OneSignal Apps for the same site?
You can have multiple OneSignal App IDs on a single origin, but it is not recommended.
Each OneSignal App creates unique VAPID keys for the Site Origin attached to that App ID. VAPID keys facilitate the subscription process to the subscriber's browser and your site origin.
If you add multiple App IDs to the same site origin, OneSignal will auto-resubscribe the user to the last visited App ID. So you will see subscribers bounce back and forth between App IDs if they are able to visit pages with different App IDs.
For example, if you subscribed to https://yoursite.com/home
using "App_ID_1", then visit https://yoursite.com/shop
using "App_ID_2", OneSignal will unsubscribe you from "App_ID_1" and then auto-subscribe them to "App_ID_2".
You will see many unsubscribed devices on each app, as users bounce between them.
The recommended approach is to Add Data Tags to devices in order to differentiate them based on URLs.
What if my site is in a subfolder?
Web push is configured at the origin level.
If your site is hosted in a subfolder, like https://example.com/blog
(where blog
is the subfolder), your web push domain will be https://example.com
. Continue the setup process with your main site origin. If you must add the service workers to the subfolder see Customizing Your Service Worker Integration.
Can OneSignal SDK files be served from a subfolder of my site?
Yes, please see OneSignal Service Worker guide for more details.
Why does my site require a label?
The Web Push Standard adopted by all major web browsers requires notifications from an HTTPS domain with technologies that support web push (specifically, the ability to upload files to the root directory).
Why do you require a label for my website builder?
Several website builders must the OneSignal HTTP SDK that requires a label, because these technologies do not allow files to be uploaded to the root directory. These site builders include:
- Blogger
- Shopify
- Squarespace
- Weebly
- Some Wordpress implementations
- Some Drupal implementations
- Some Joomla implementations
- Some Magento implementations
Why can't I change my site's label?
OneSignal allows you to experiment with different labels when you have fewer than 100 web subscribers to give you some extra flexibility while you're still deciding how to use push notifications.
After your app has 100+ web subscribers, this setting is disabled, and you must start over with a new OneSignal app to use a different label.
We do this because changing your label can cause subscribers to receive duplicate notifications.
Can I host the OneSignal SDK files myself?
We highly recommend against this. Browsers are constantly changing and updating how users and websites can use web push notifications.
OneSignal makes sure these changes are implemented as soon as possible to make sure your site is working correctly. You should use the OneSignal CDN URL supplied in the Web Push Settings instead of hosting the files yourself, unless our documentation specifically tells you to do so.
Can I customize the OneSignal init code?
You can customize the OneSignal init
code only if you've selected Custom Code Setup when setting up your OneSignal app.
If you select Typical Setup or Website Builder when setting up your OneSignal app, any init
code you add to your site's pages will be ignored by the OneSignal SDK.
How do I test my site on a local environment?
See Web Push Advanced Options.
Can OneSignal integrate with another Service Worker on my site or a Progressive Web App?
Yes! Please see Integrating Multiple Service Workers.
Why use .push in the SDK?
You may have noticed the need to wrap your OneSignal calls with OneSignal.push(function() { ... })
OneSignal.push(function() {
/* ... */
});
The OneSignal SDK is loaded asynchronously on your page. For example:
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async"></script>
You can read more about the async attribute here and here.
Basically, a script without an async
attribute stops the loading of the rest of the page while it is fetched and executed, but async
scripts allow the rest of the page to load, while it is eventually fetched and executed.
This presents a problem for page scripts that depend on the OneSignal
variable existing.
Most of the OneSignal code examples begin with:
window.OneSignal = window.OneSignal || [];
This creates a OneSignal variable, and if OneSignal is already loaded, it's then assigned to the loaded instance. Otherwise, the OneSignal variable equals an empty array - []
.
All arrays have a .push() function
, so at this point, the OneSignal variable is simply an array of functions we're pushing on to it.
When the SDK finally loads, the SDK processes all the functions pushed so far and redefines .push().
Original Stack Overflow discussion: http://stackoverflow.com/a/38466780/555547
Updated over 1 year ago