OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Web Push FAQ

Common questions about OneSignal's Web Push Notifications

What Platforms Support Web Push Notifications?

All major browsers support web push. Android devices may also receive web push notifications, in addition to notifications from apps. Below is a complete list of platforms and browsers that offer support for web push notifications.

Browser Support by Operating System

Note: Incognito Mode, Private Browsing Mode, and Guest Browser Mode do not support web push.

Note: Internet Explorer is no longer receiving feature updates. Microsoft has switched browser development to the Edge platform.

Browser
Windows PC
macOS
Android
iOS (iPhone, iPad)

Yes

Yes

Yes

No

Yes

Yes

Yes

No

No

Yes

N/A

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

N/A

N/A

N/A

Yes

N/A

No

N/A

Yes

No

No

N/A

N/A

N/A

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

Apple does not support web push notifications on iOS at this time.


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

Browsers require 2 things for web push notifications to work:

  1. An HTTPS site
  2. 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), you must make a few changes to your OneSignal integration.

Please see How do I change my Web Push Setup for details.


How do I change my site URL?

Please see How do I change my Web Push Setup below for details.


Can I transfer subscribers from one site to another?

Web browsers, for security reasons, do not allow subscribers to be transferred from one origin (domain/site URL) to another origin.

If you changed your site's origin, your users will need to subscribe to that new site origin. See How do I change my Web Push Setup for more details.


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:

1. Only subscribe users on one origin. If you have subdomains or multiple origins, you can redirect users to the "main" origin to subscribe, then redirect them back to the other origin to continue browsing.

2. 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.

More details in our guide for setting up Complex Web Push Integrations.


What if my site supports multiple languages?

For origins that support multiple languages see our Prompting FAQ to translate prompts.


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.

For example, if you subscribed to https://yoursite.com/home using an app ID of "APP_1", then visit https://yoursite.com/shop using an app ID of "APP_2", OneSignal will unsubscribe you from "APP_1" and then subscribe you to "APP_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.

On the other hand, if your site uses a subdomain (like https://blog.example.com), your web push domain will need to be https://blog.example.com.


Why does my site require a label?

The Web Push Standard adopted by all major web browsers requires notifications to come from an HTTPS address with technologies that support web push (specifically, the ability to upload files to the root directory).

OneSignal has developed a work-around since not all sites fully support these technologies - even if the websites themselves support HTTPS.

Our work-around (called the OneSignal HTTP SDK) creates a site that we host for the sole purpose of delivering your notifications. This site (os.tc) creates a unique subdomain based on your label (like yoursite.os.tc) that is displayed to users when they receive your notifications.

For example:

The label you select must be unique - if somebody else is already using it, you must choose another.


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 OneSignal SDK files be served from a subfolder of my site?

It is highly recommended to add the OneSignal service workers to your root directory so they are accessible at https://yoursite.com/OneSignalSDKWorker.js. This allows you to subscribe users under the full scope of your site.

If you do not have root access, the OneSignal service workers files can be loaded from a subdirectory, but one of the two methods below must be used for the user to officially be subscribed.

Method 1. Add an Additional HTTP Header

The OneSignal service worker Files (OneSignalSDKWorker.js & OneSignalSDKUpdaterWorker.js) can be served from a sub-directory only if these two files are served with the additional HTTP header of "Service-Worker-Allowed: /".

To learn more about setting an HTTP Header with Service-Worker-Allowed, see this guide.

Method 2. Subscribe Under a Subdirectory

If you are not able to add an HTTP header, you can add the service worker files to a subdirectory like:

https://yoursite.com/subdirectory/OneSignalSDKWorker.js
https://yoursite.com/subdirectory/OneSignalSDKUpdaterWorker.js

However, you can only subscribe users to your site on pages within /subdirectory. You will not be able to subscribe users on the top level domain yoursite.com.

Users will not be able to subscribe unless they are on the /subdirectory/ path. They will not be able to subscribe to your home page, and cannot subscribe to pages that are not under the /subdirectory/ .

If you decided to use one of the above methods, follow our Customizing Service Worker Integration guide for setting up OneSignal accordingly.

A 3rd method to work around this is to setup your site with our HTTP Integration selecting "My site is not fully HTTPS" in the OneSignal Dashboard > Settings > Browser configuration.


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?

If you have a main production site, and also a local test site, please create a separate OneSignal development app for testing locally.

Web push apps can only be used on the site URL specified in the settings in the OneSignal dashboard. If you have an existing production app pointing to https://your-site.com, you cannot simultaneously use this app on https://localhost. You will need to create a separate app in OneSignal with https://localhost as the site URL.

Additionally, apps with more than 100 users will be unable to change their site URL. See How do I change my Web Push Setup? for more details.


How do I use HTTPS for localhost?

Google Chrome treats http://localhost and http://127.0.0.1 as secure origins, allowing HTTPS integrations even on HTTP.

Please note that these HTTP origins are the only exceptions, and HTTP production sites will not have a working HTTPS integration.

OneSignal only supports this if you add:

  • For Custom Code integrations: allowLocalhostAsSecureOrigin: true to your OneSignal init options (top level, on the same level as appId).
  • For Typical Site integrations: Enable Treat HTTP localhost as HTTPS for testing in the Advanced options section of Web Push settings page in the OneSignal dashboard.

Additionally, if you're testing localhost on HTTPS with a self-signed certificate, you may have to ask Chrome to ignore invalid certificates for testing with: --allow-insecure-localhost. Firefox and Safari provide built-in mechanisms to add exceptions for security certificates.

For Local WordPress Development

In the plugin editor > OneSignal plugin > OneSignal-public.php file, find this code:

echo "oneSignal_options['appId'] = '".esc_html($onesignal_wp_settings['app_id'])."';\n";

Then under it add:

echo "oneSignal_options['allowLocalhostAsSecureOrigin'] = true;\n";

Now click Save, and you can then test that everything is loading as expected on localhost.


How do I change my Web Push Setup?

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

For security purposes, browsers do not allow subscribers to be moved to other origins.

Sites with different origins include:

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

If you changed your site origin, the best solution is to set up a new OneSignal app and have your users subscribe to the new site's 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.

We recommend sending a couple notifications periodically from the old domain, letting users know that the site has moved and that they should subscribe to the new site URL to stay updated.

For more details, see Can I set up multiple websites or subdomains with a single OneSignal App?


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:

var 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 11 days ago


Web Push FAQ


Common questions about OneSignal's Web Push Notifications

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.