What are Service Workers?

Web Push Notifications for most browsers (not Safari) require Service Worker files to be available on your domain in order to subscribe and receive web push notifications.

These files generally get downloaded upon accepting web notifications.

How Do I Integrate OneSignal's Service Worker Files?

❗️

Skip if using WordPress and Shopify Plugins

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

1. Download .js files

Download OneSignal Service Worker Files

2. Upload .js files to a subdirectory on your domain

Place these .js files in a path you will never link users to, this way they won't conflict with any other ServiceWorkers now, or in the future.

• Example https://mysite.com/push/onesignal/

These files should be put in a permanent location path that will never change! Once a ServiceWorker is registered with the browser it is difficult to change.

3. How to upload files

If you are unsure how to upload files to your server, some common options:

Option 1: FTP

• Use an FTP Server like FileZilla to upload the files to your root directory
• Here is a great step-by-step guide.

Option 2: Control Panel

• Use your hosting provider's control panel like cPanel to upload files.

Option 3: Contact your hosting provider

• Most hosting providers will be more than happy to assist you in uploading files to your site.
• Just send them the zip file above and ask them to unzip it in your site's root directory.

Option 4: What if I can't upload .js files to my domain at all?

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.

4. Service Worker Configuration

Almost done, you now need to tell OneSignal where I can find your service worker by following the section below.

Customizing Your Service Worker Integration

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

• The files must be served with a content-type of application/javascript; charset=utf-8
• 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:

• Place 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, go to your App's Settings > All Browsers

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: '/push/onesignal/' };
        OneSignal.SERVICE_WORKER_PATH = 'push/onesignal/OneSignalSDKWorker.js'
        OneSignal.SERVICE_WORKER_UPDATER_PATH = 'push/onesignal/OneSignalSDKUpdaterWorker.js'
        OneSignal.init(initConfig);
    });
</script>

Service Worker Migration Guide

🚧

Recommended but Not Required

Follow this guide if you already have a large amount of web push subscribers and you want to change OneSignal's ServiceWorker settings.

Motivation

OneSignal’s ServiceWorker defaults to a root scope which may create the following issues for your site:

• Conflict with a PWA
• Conflict with an AMP setup
• Conflict with your caching ServiceWorker, or any other ServiceWorker feature that requires root scope
• Your site has security requirements that do not allow third-party ServiceWorker code to run on a scope that controls a pages your users will visit.

If one or more apply to you then please follow the this guide.

Picking a OneSignal ServiceWorker Scope

It is recommended you pick a Service Worker scope path you will never link a user to, but is still clear what it does. Example: /push/onesignal/. This way your PWA, AMP, or any other caching ServiceWorker can control the page a user views to work correctly.

It is ok to put multiple service workers in the same location path, but MUST have unique scope path.

Option 1 - Safely change the OneSignal ServiceWorker Scope

🚧

This section only covers changing the Service Worker Scope!

It is recommend to only change the scope if possible, changing the filename or location path of the Service Worker itself has additional considerations. Pay close attention to both the details of which scenario applies to you as well as each step to ensure you don’t lose subscribers or run into notification display issues

Setup Type 1 - Default OneSignal Setup - Scope root “/” AND default OneSignalSDKWorker.js Contents

Confirm the contents of your OneSignalSDKWorker.js file is as follows.
(Without any other non-OneSignal code you may need in it)

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

In this case you can change the OneSignal scope to anything you choose to make room for another Service Worker to be placed at the root scope. See “Customizing Your Service Worker Integration” above

🚧

Keep Service-Worker-Allowed Header

If your OneSignalSDKWorker.js is not hosted on root of your domain today, example you do NOT have it hosted like this: https://mysite.com/OneSignalSDKWorker.js then you MUST keep hosting it with the Service-Worker-Allowed header for an extended period of time. (1 year or more is recommended)

• If possible we recommend adding a comment in your backend code or your internal documentation to ensure it doesn’t get accidentally removed.

Setup Type 2 - Uncommon - Scope root “/” AND OneSignalSDKWorker.js (or your configured filename) contains OneSignal + other code or importScripts

🚧

Combined ServiceWorker file

This is less common but you may have already done this by following this OneSignal guide “Integrating Multiple Service Workers”. If this setup still meets all your requirements highly recommend keeping your setup as is due to the complex and two phase roll out required break up the merged ServiceWorker file that handles push events.

This section applies if you have OneSignal AND either some other custom code or importScript like the following in in your current Service Worker.

// OneSignal ServiceWorker 
importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');
// And some other site specific code in the same file example.
importScripts('https://site.com/my-other-service-worker.js');

1. Add a code comment to your existing ServiceWorker file above this line importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js'); to keep it for a extended period of time. (a year or more is recommend, depends on how long you want to keep sending pushes to users who never re-visit your site).

   • Example: // KEEP Until YYYY-MM-DD: Required for pushes to work correctly for users who have not re-visited to migrate to the new OneSignal specific ServiceWorker.

2. Create a new OneSignalSDKWorker.js under a different directory, such as /push/onesignal/ with the following single line of code

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

3. Follow the guide on “Customizing Your Service Worker Integration” to change your scope and filename and path.

4. At this point new and returning users will automatically be subscribed to the new OneSignal ServiceWorker.

5. Wait the amount of time (a year or so) as noted in step 1.

6. Follow the OneSignal - “Delete Users” guide to delete users older than the timeline you picked.

7. Lastly finally remove the importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js'); line with the comment from your original root ServiceWorker.

Option 2 - Safely changing the OneSignal ServiceWorker Filename or location

❗️

Not recommend

It is highly recommend you only change the Scope if it meets all your requirements due to the complex and two phase roll out required move a ServiceWorker file that handles push events.

Setup Type 1 - Default OneSignal Setup - Scope root “/” AND default OneSignalSDKWorker.js Contents

Confirm the contents of your OneSignalSDKWorker.js file is as follows.
(Without any other non-OneSignal code you need in it)

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

1. In your existing OneSignalSDKWorker.js file add a code comment to keep the line for an extended period of time (a year or more is recommend, depends on how long you want to keep sending pushes to users who never re-visit your site).

   • Example: // KEEP Until YYYY-MM-DD: Required for pushes to work correctly for users who have not re-visited to migrate to the new OneSignal ServiceWorker file located at UPDATE YOUR URL HERE: https://mysite.com/push/onesignal.OneSignalSDKWorker.js.

2. Create a new OneSignalSDKWorker.js under a different directory, such as /push/onesignal/ with the following single line of code.

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

3. Follow the guide on “Customizing Your Service Worker Integration” to change your scope and filename and / or path.

4. At this point new and returning users will automatically be subscribed to the new OneSignal ServiceWorker.

5. Wait the amount of time (about a year) as noted in step 1.

6. Follow the OneSignal - “Delete Users” guide to delete users older than the timeline you picked.

7. Lastly finally remove the old ServiceWorker file.

Setup Type 2 - Uncommon - Scope root “/” AND OneSignalSDKWorker.js (or your configured filename) contains OneSignal + other code or importScripts

See “Option 1 - Safely change the OneSignal ServiceWorker Scope” above as the steps are the same for this kind of integration.

Migrating OneSignal ServiceWorker scope - FAQ

Why must I keep hosting the original ServiceWorker file URL if I change the name or location path?

This is required for those users who have not re-visited your site for the new filename to be picked up. The original ServiceWorker file will be fetched by the browser each time you send a push (if past cache expire time, max cache is 24 hours).
You will see a spike in 404 errors returned from your hosting provider when sending a push if the original ServiceWorker file isn’t available. This may result more requests to your server. This also means those users won’t be getting the new OneSignal features and fixes.

Integrating Multiple Service Workers

❗️

Deprecated (as of 3/17/2021)

OneSignal's ServiceWorker no longer requires page control. This means you should instead follow the Customizing Your Service Worker Integration to change the Scope instead. Or Migrating OneSignal ServiceWorker if you already have 100 or more web push subscribers.

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.