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 api.onesignal.com
Browser's site data must NOT be cleared, otherwise the push will become unsubscribed
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. See OneSignal Service Worker.

iOS / iPadOS Specific Requirements:

Device is running iPadOS / iOS 16.4 or newer
Site has the requirement to be considered a Web App
Has a manifest, normally referred to as a manifest.json
End-User has added site the the home screen and has opened it from there
User still must be prompted like normal for notification permissions after opening the web app.

What Platforms Support Web Push Notifications?

All major browsers support Web Push. Android, Huawei 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 offer support for 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	No
Firefox	Yes	Yes	Yes	No
Safari	No	Yes	No	Yes
Microsoft Edge¹	Yes	Yes	Yes	No
Opera¹	Yes	Yes	Yes	No
Samsung Internet Browser¹	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

Note ¹: 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 ²: 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+.
Mozilla Firefox	Firefox v47+
Apple Safari	Safari 10+ on macOS Safari 16.4+ on iOS and iPadOS 16.4+

How do I change my domain?

Browsers have setup web push in a way that ties subscribers to a specific origin (domain/site URL).

For security purposes and browser's same origin policy, browsers do not allow subscribers to be moved to other origins. This is not a OneSignal limitation, any claims that you can move subscribers from one site origin to another means the subscribers are not tied to your site origin.

Sites with different origins include:

Changing from HTTP to HTTPS
www.mysite.com and non-www version
domain1.com and domain2.com or sub.domain1.com and sub.domain2.com

If you changed your site origin, there are two options:

Option 1. Setup a new OneSignal App

Set up a new OneSignal app and have your users subscribe to the new site origin under this new OneSignal app. You will not able to import subscribers from one origin to another origin. You can continue sending push notifications to your subscribers on the old origin (old OneSignal app), but your users will need to re-subscribe to the new origin to get push from the new domain.

The recommended steps for migration are as follows:

Setup a new OneSignal App ID for the new site domain.
Continue to send push from the old OneSignal App with old site domain. In the "Launch URL" of the notifications, use the new site domain.
After 2 weeks to 2 months (depending on how many notifications you send per day and how many subscribers you get on the new origin) you can then stop sending from the old OneSignal app and only use the new OneSignal app.

For example if you send 1+ notifications per day, then 2 weeks should be enough time to have your users subscribe to the new domain.
If you send 2+ notifications per week, then 2 months should be enough time.
If you send the same message from the old OneSignal App and new OneSignal app, any subscribers under both will get duplicate messages. This is why the timeframes are recommended.

You can send a couple "We've moved, click here to visit our new site to subscribe again and stay updated" messages. This will help alert people that they may not get push from your site if they don't return to subscribe. Best to send this at the beginning of the move and last message sent from the app.

Unfortunately all websites and user-bases are different. Be prepared to lose subscribers in the short term.

Option 2. Update App API & Delete Users

You can use the Update an app API to change the site url with the following properties:

name - the name of your app or site
chrome_web_origin - the new site URL you want to change to.
chrome_web_default_notification_icon - the image URL of your icon.

Be aware that the subscribers under the "old" origin that is being replaced will get double notifications if they subscribe to the "new" origin. This is because the subscription push token is tied to the site origin and you may now get 2 different origin push tokens for the same user.

To get around this, we recommend deleting all the "old" web push subscribers. You can use "Device Type is Web Push" for the segment and then Delete Users within the segment.

Can I setup multiple websites or subdomains with a single OneSignal App?

Browsers have implemented web push in a way that works best with only one main origin (domain/site url). Separate origins of a site cannot be merged to one app.

For example, browsers will not allow https://mysite.com and https://www.mysite.com to both collect the same subscribers.

Due to this browser limitation, it is not possible to unify multiple origins into a single OneSignal App. This can cause issues with duplicate notifications, and a poor user experience.

Generally, your options are:

Only subscribe users on one origin. If you have subdomains or landing pages or any other sites using multiple origins, you can redirect users to the "main" origin to subscribe, then redirect them back to the other origin to continue browsing.
Create separate OneSignal Apps for separate origins. Notifications will arrive independently of each other. This means users who subscribe to multiple sites will receive duplicate notifications if you send the same notifications on all sites.

What should I do if I upgraded my site to HTTPS?

Browsers require 2 things for web push notifications to work:

An HTTPS site
Service worker files added to the server

If you had an HTTP site, and upgraded to HTTPS (or, you are now able to add service workers to your site), browser's will treat the HTTPS site as a new origin.

Please see How do I change my Domain for details.

Can I transfer subscribers from one site to another?

If you changed your site's origin, your users will need to subscribe to that new site origin. See How do I change my Domain for more 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.

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?

See the Web SDK docs for more details.

After OneSignal released a web SDK update, how long til those changes go into effect?

Any updates to our Service Worker files have a 24 hour cache and our web SDK has a 3 day cache.