​

What are service workers?

A Service Worker is a background script that runs separately from the main browser thread. It allows features like push notifications, offline experiences, and background syncs. When a user subscribes to Web Push, the service worker is downloaded and persists even when they navigate away—enabling push notifications at any time.

​

Migrating from another push provider

If you are switching providers, review our guide:

Migrating to OneSignal from another service

​

How to integrate OneSignal’s service worker

​

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

You now need to tell OneSignal where to find the Service Worker and set the registration scope. By default, the OneSignal SDK sets this to be the root of your site. If you placed the OneSignalSDKWorker.js file in your site’s root like https://yoursite.com/OneSignalSDKWorker.js then no further action needed. However, it is recommended to place the Service Worker file in a subdirectory with a registration scope that will never be used, like /push/onesignal/.

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.

<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
            },
            serviceWorkerParam: { scope: "/myPath/myCustomScope/" },
            serviceWorkerPath: "myPath/OneSignalSDKWorker.js",
        });
    });
</script>

​

OneSignal Service Worker migration guide

Follow this section only if you already use OneSignal, have a large amount of web push subscribers, and you want to change OneSignal’s Service Worker settings.

Migration steps for the OneSignalSDKWorker.js file (click to expand)

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.

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");

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");

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

​

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.