OneSignal Service Worker

Overview

This guide covers how to configure the OneSignal Service Worker for Web Push Notifications.

If you are using our WordPress plugin, the OneSignal Service Worker file gets added automatically and you should not add these files to your site manually. Return to WordPress setup for more information.

What are service workers?

A Service Worker is a background script that runs in a separate thread from the main page. It enables features like push notifications, offline caching, and background sync. It’s installed when your site registers it and, although not always running, can be woken to handle events (including push) even after the user navigates away.

How to integrate OneSignal’s service worker

As you follow our Web SDK Setup guide, you will be provided the OneSignalSDKWorker.js service worker file.

Download the .js file

Download the OneSignalSDKWorker.js file from the OneSignal dashboard or Download the OneSignal Service Worker File here.

Upload the .js file to your server

Our SDK defaults to looking in your site’s root for the OneSignalSDKWorker.js file, for example: https://yoursite.com/OneSignalSDKWorker.js You can simply upload this file to the root directory of your site and return to the Web push setup guide for next steps. However, it is recommended to place this OneSignalSDKWorker.js file in a subdirectory path that you will never link users to like https://yoursite.com/push/onesignal/OneSignalSDKWorker.js. You can place this file in the root, but it may conflict with other Service Workers you have now or may add in the future. Also, the file should be put in a permanent location path that will never change. Once a Service Worker is registered with the browser, it is difficult to change.

Service Worker configuration

The OneSignal service worker file OneSignalSDKWorker.js must meet these requirements:

The file must be publicly accessible, meaning you should be able to navigate to the file in a browser and see the code.
The file must be served with a content-type of application/javascript; charset=utf-8.
The file must point to the same site origin (your site domain). Pointing to a Service Worker on a different origin is not allowed. No CDNs or subdomains.

Confirm the service worker is setup correctly

Visit the service worker in your browser. You should see the code for the service worker: importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

If you uploaded the OneSignalSDKWorker.js file to your site’s root (it is accessible at https://yoursite.com/OneSignalSDKWorker.js) then no further action is needed. However, if you put it in a subdirectory like https://yoursite.com/push/onesignal/OneSignalSDKWorker.js then you will need to set the registration scope as follows:

Typical site setup
Custom Code Setup

In the OneSignal dashboard, go to your App’s Settings > Push & In-App > Web SettingsUnder Advanced Push Settings, toggle the Customize service workers paths and filenames switch and input your data.

Path to service worker files is the directory to where the OneSignal Service Worker file will be available. If the Service Worker is available at: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js then the path is: /push/onesignal/
Main and Updater service worker filenames is the name of the Service worker file. It should be OneSignalSDKWorker.js but if you changed it, make sure to use the .js file extension. For example, if your server forces files to have lowercase, you can set the filename to be onesignalsdkworker.js
Service worker registration scope are the pages this file can work on. This should be a path that you will never link users to and never host any pages from now or in the future. A common path example: /push/onesignal/ and scope could be the same path or deeper like: /push/onesignal/js/

To set up the service worker files in a subdirectory on Custom Code Setup, set up your init call similar to this:

html

  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
      window.OneSignalDeferred = window.OneSignalDeferred || [];
      window.OneSignalDeferred.push(async function(OneSignal) {
          await OneSignal.init({
              appId: "YOUR_APP_ID",
              notifyButton: {
                  enable: true
              },
              serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
              serviceWorkerParam: { scope: "/push/onesignal/js/" },
          });
      });
  </script>

serviceWorkerPath is the directory and filename to where the OneSignal Service Worker file will be available. If the Service Worker is available at: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js then the path is: push/onesignal/OneSignalSDKWorker.js
serviceWorkerParam sets the scope of pages this file can work on. This should be a path that you will never link users to and never host any pages from now or in the future. A common path example: /push/onesignal/ and scope could be the same path or deeper like: /push/onesignal/js/

Service worker setup is complete!Return to the Web SDK Setup guide for next steps.

OneSignal Service Worker migration guide

This section is only for customers that already use OneSignal, have a large amount of web push subscribers, and want to change the OneSignal Service Worker settings. This is not recommended unless you have a specific reason to do so.

Migration steps for the OneSignalSDKWorker.js file

This guide is only for customers that already use OneSignal on their website currently and want to move the OneSignalSDKWorker.js file to a different path or scope.

OneSignal’s Service Worker 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 Service Worker, or any other Service Worker feature that requires root scope
Your site has security requirements that do not allow third-party Service Worker code to run on a scope that controls a page your users will visit.

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

Picking a OneSignal Service Worker 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: Change scope
Option 2: Change filename or location

Safely change the OneSignal 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 the same as found in Download the OneSignal Service Worker File here. (Without any other non-OneSignal code you may need in it)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 above Customize Your Service Worker Integration.

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

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.

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//And some other site specific code in the same file example.
importScripts("https://site.com/my-other-service-worker.js");

Keep your existing service worker code.

Add a code comment to your existing ServiceWorker file above this line importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.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.

Create a new service worker file

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/web/v16/OneSignalSDK.sw.js");

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

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

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

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

Remove comment from original service worker

Lastly finally remove the importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); line with the comment from your original root ServiceWorker.

Safely changing the OneSignal ServiceWorker Filename or location

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/web/v16/OneSignalSDK.sw.js");

Add a comment to your existing service worker

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.

Create a new service worker file

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

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

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

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

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.

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

OneSignal Service Worker

Overview

What are service workers?

How to integrate OneSignal’s service worker

Download the .js file

Upload the .js file to your server

Service Worker configuration

Confirm the service worker is setup correctly

OneSignal Service Worker migration guide

Picking a OneSignal Service Worker Scope

Safely change the OneSignal Service Worker Scope

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

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

Safely changing the OneSignal ServiceWorker Filename or location

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

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

Migrating OneSignal ServiceWorker scope - FAQ

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

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

​Overview

​What are service workers?

​How to integrate OneSignal’s service worker

​Download the .js file

​Upload the .js file to your server

​Service Worker configuration

​Confirm the service worker is setup correctly

​OneSignal Service Worker migration guide

​Picking a OneSignal Service Worker Scope

​Safely change the OneSignal Service Worker Scope

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

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

​Safely changing the OneSignal ServiceWorker Filename or location

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

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

​Migrating OneSignal ServiceWorker scope - FAQ

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

Overview

What are service workers?

How to integrate OneSignal’s service worker

Download the .js file

Upload the .js file to your server

Service Worker configuration

Confirm the service worker is setup correctly

OneSignal Service Worker migration guide

Picking a OneSignal Service Worker Scope

Safely change the OneSignal Service Worker Scope

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

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

Safely changing the OneSignal ServiceWorker Filename or location

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

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

Migrating OneSignal ServiceWorker scope - FAQ