Overview
This guide covers how to configure the OneSignal Service Worker for Web Push Notifications.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 service workers work
How to integrate OneSignal’s service worker
As you follow our Web SDK Setup guide, you will be provided theOneSignalSDKWorker.js
service worker file.
Download the .js file
Download theOneSignalSDKWorker.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 theOneSignalSDKWorker.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 fileOneSignalSDKWorker.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
ofapplication/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");

Example of the service worker code
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

Service worker configuration for Typical site setup
- 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 beonesignalsdkworker.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/
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
Migration steps for the OneSignalSDKWorker.js file
OneSignalSDKWorker.js
file to a different path or scope.- 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.
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
Setup Type 1. Default OneSignal Setup - Scope root “/” AND default OneSignalSDKWorker.js Contents
Confirm the contents of yourOneSignalSDKWorker.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.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
importScript
like the following in in your current Service Worker.Keep your existing service worker code.
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
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
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
line with the comment from your original root ServiceWorker.