What are Service Workers?

Web Push Notifications for Chromium-based browsers (not Safari) require Service Worker files to be downloaded to the subscriber's browser in order to receive web push notifications.

These files generally get downloaded upon opt-in to web push notifications.

If you have other service workers for cases like a Progressive Web App, or custom functionality, see below for details about Integrating Multiple Service Workers.

How do I integrate OneSignal's Service Worker files?

❗️

WordPress and Shopify websites

The OneSignal Service Worker files get added automatically through our plugins, and you should not add these files to your site manually.

Download the files

If you haven't already downloaded the OneSignal service worker files, you can do so here: Download OneSignal Service Worker Files

There are 2 options for adding these files to your site:

Add files to Root Directory

Recommended since this will allow your users to subscribe to push on any page of your site.

Add files to a Subdirectory

If you do not have root access, the OneSignal service worker files can be loaded from a subdirectory, but one of these two methods must be used to subscribe the device:

Method 1. Add Service-Worker-Allowed Header to your server

The OneSignal service worker Files (OneSignalSDKWorker.js & OneSignalSDKUpdaterWorker.js) can be served from a sub-directory and allowed to run at the root scope by adding the HTTP header of "Service-Worker-Allowed: /".

More details in W3C Service worker specifications.

Helpful stack overflow details: node.js example, IIS or nginx example.

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 or other pages 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.

🚧

What if neither option works for me?

As long as you can add Javascript to your site, you can always follow our HTTP Integration selecting "My site is not fully HTTPS" in the OneSignal Dashboard > Settings > Browser configuration.

We will provide you a subdomain to subscribe users under without needing service workers.

Customizing Your Service Worker Integration

The OneSignal service worker files (OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js) must meets these requirements:

• The files must be served with a content-type of application/javascript
• The files must point to the same site origin (your site domain). Pointing to a service worker on a different origin is not allowed.

Follow these steps for your specific setup if you need to:

• put the OneSignal service worker files into a subdirectory
• rename the files
• include multiple service workers on an origin

SDK Parameter Reference for Service Workers

Typical Site Setup - Service Worker Customizations

In the OneSignal dashboard, select your app from the All Apps page, then go to Settings. Under Web Push Platforms, click All Browsers (except Safari).

In the Advanced section, toggle the Service Workers switch.

Custom Code Setup - Service Worker Customizations

To set up the service worker files in a subdirectory on Custom Code Setup, set up 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>

Integrating Multiple Service Workers

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.

Our service worker files (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 the OneSignal 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');

It is recommended to 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');

If you customized the path, scope, or filenames of the OneSignal service workers (or added the importScripts code from our service workers into the your current service workers), see Customizing Service Worker Integration.

Integrating with Super PWA Plugin for Wordpress

The most common PWA plugin for Wordpress is Super PWA.

Please see Super PWA's guide if you're seeing an "Action required to integrate…" banner in your Wordpress admin after installing and setting up OneSignal's Wordpress Plugin.