OneSignal Push Notification Service Documentation

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 Setup FAQ

Frequently asked questions about OneSignal Web Push Setup.

OneSignal Web Push Integration

Why can't I create another App for my site?

See below Can I associate multiple websites/subdomains with a single OneSignal App?

Can I associate multiple websites/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.

Due to this browser limitation, it is not possible to unify multiple OneSignal Apps into one. This can cause issues with duplicate notifications and a poor user experience, which is why creating multiple apps for the same origin is not allowed.

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.

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

For more advanced integrations, please see our Web Push Complex Integrations Guide.

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 (e.g. 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 does my website builder require a label?

Several website builders must use of the OneSignal HTTP SDK that requires a label because these technologies do not allow files to be uploaded to the root directory. These include:

  • Blogger
  • Shopify
  • Squarespace
  • Weebly
  • Some Wordpress implementations
  • Some Drupal implementations
  • Some Joomla implementations
  • Some Magento implementations

Why can't I change my label?

OneSignal allows you to experiment with different labels when you have fewer than 100 web users to give you some extra flexibility while you're still deciding how to use push notifications. After your app has 100+ web users, 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 users to receive duplicate notifications.

What if my site is in a subfolder?

Web push is configured at the domain or subdomain level.

If your site is hosted in a subfolder, like example.com/blog (where blog is the subfolder), your web push domain will be example.com.

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

OneSignal SDK Files & Code

Can I host the OneSignal SDK myself?

No, you should use the CDN URL supplied in the Web Push Settings instead.

Troubleshooting: adding code in the right location

https://cdn.onesignal.com/sdks/OneSignalSDK.js must be located in the <head> of all pages. This ensures all pages can subscribe for notifications, and that session count can be accurately counted.

Can OneSignal SDK files be served from a subfolder of my site?

OneSignalSDKWorker.js & OneSignalSDKUpdaterWorker.js

These files should not be renamed and the files should be served from the top-level root. The service worker being pointed to must be on the same origin. Pointing to a service worker on a different origin is not allowed. If you cannot serve them from the top-level root, your options are:

1. HTTP Header

These two files can be served from a sub-directory only if these two files are served with an additional HTTP header "Service-Worker-Allowed: /".

These two files make up our service worker, a background web worker to display notifications. Parts of our web SDK depend on the service worker being registered properly: it should be served with the HTTP header "Service-Worker-Allowed: /" if served from a subfolder, otherwise it should be served at the top-level root of your site.

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 initialize OneSignal on pages within your "subdirectory" like yoursite.com/subdirectory. You will not be able to subscribe users on the top level domain yoursite.com

Typical Site Setup & Non-WordPress Site Builders

In the dashboard setup configuration under step 5 Advanced, toggle the "Service Workers" switch and add the path, filenames and registration scope.

Custom Code Setup

To setup the service worker files in a subdirectory on Custom Code Setup. Setup your init call similar to this:

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
   var OneSignal = window.OneSignal || [];
    var initConfig = {
        appId: "YOUR_APP_ID",
        notifyButton: {
            enable: true
        },
    };
    OneSignal.push(function () {
        OneSignal.SERVICE_WORKER_PARAM = { scope: '/subdirectory/' };
        OneSignal.SERVICE_WORKER_PATH = 'subdirectory/OneSignalSDKWorker.js'
        OneSignal.SERVICE_WORKER_UPDATER_PATH = 'subdirectory/OneSignalSDKUpdaterWorker.js'
        OneSignal.init(initConfig);
    });
</script>

The path and scope should look similar to /subdirectory/ also add the names of the service workers OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js unless you changed the names, then add the new name.

3. My site is not fully HTTPS

The final option is to go into the OneSignal dashboard configuration and select "My site is not fully HTTPS" and add a 'Label" aka a subdomain. Then press "Save" and continue the setup.

Can OneSignal integrate with another service worker on my site or a Progressive Web App?

Note: This only applies if your site has another service worker. If you are developing a Polymer site or a Progressive Web App, you most likely have another service worker.

Attention WordPress Users Only

The most common PWA plugin is Super PWA, all PWAs have an issue with our service worker that requires a bit of extra setup.

Please see Super PWA's guide to resolving this issue

Our service workers OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js overwrite other service workers that are registered with the topmost (site root) service worker scope. The solution is to merge all other service worker scripts into our service worker scripts using importScripts() and to register the merged service worker instead of the original worker.

Both OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js contain the following code:

importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');

Please modify both OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js to import your other service worker scripts, like:

importScripts('https://site.com/my-other-service-worker.js');
importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');

We recommend the above approach instead of importing our service worker into another file because our web SDK replaces other workers that are registered on the root scope.

Additionally, please be sure to modify your site's code to register OneSignalSDKWorker.js instead of your own worker. You can do this with code like:

navigator.serviceWorker.register('/OneSignalSDKWorker.js');

More about service workers can be read here.

Can I customize the OneSignal init code?

You can customize the OneSignal init code only if you've selected the Custom Code integration. If you select Typical Site or Website Builder, any init code you add 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 development app for testing locally.

Web push apps can only be used on the Site URL specified in your OneSignal dashboard. If you have an existing production app pointing to https://your-site.com, you can't simultaneously use this app on https://localhost. Additionally, apps with more than 100 users cannot change the Site URL, so you can't change your app's Site URL to point to https://localhost.

Treating http://localhost as HTTPS

Chrome treats http://localhost and http://127.0.0.1 as secure origins, allowing HTTPS integrations even on HTTP. Please note 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 the web config editor.

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.

Why use .push in the SDK?

See: http://stackoverflow.com/a/38466780/555547

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, e.g.:

<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 existing. If the OneSignal variable does not yet exist, how can OneSignal be used?

Most of the OneSignal code examples begin with:

var OneSignal = window.OneSignal || [];

This says: create a OneSignal variable, and if OneSignal is loaded already assign it to the loaded instance, otherwise let OneSignal equal the 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().

What's Next

Web Push Quickstart

Web Push Setup FAQ

Frequently asked questions about OneSignal Web Push Setup.

Suggested Edits are limited on API Reference Pages

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