Skip to main content
The OneSignal service worker (OneSignalSDKWorker.js) is a JavaScript file hosted on your server that is required for web push notifications. It enables your site to receive and display notifications, even when the user is not on your page.
Diagram showing the OneSignal service worker receiving a push event and displaying a notification

How the OneSignal service worker processes push notifications

If you use the WordPress plugin, skip this guide. The plugin hosts OneSignalSDKWorker.js in its sdk_files directory and configures the path for you. Do not upload the file to your site root or set a custom path in the dashboard or in code. See WordPress setup. Shopify also deploys the worker for you. See Shopify setup.

​
Service worker setup

Create a dedicated OneSignalSDKWorker.js file for OneSignal push notifications. If your site already has a service worker and you want to use a single file, see Combining multiple service workers instead.
1

Download or create OneSignalSDKWorker.js

Download the file from the OneSignal dashboard during Web SDK setup or from GitHub.Alternatively, create a file named OneSignalSDKWorker.js with the following single line of code:
You can rename the file if needed (e.g., onesignalsdkworker.js, ossw.js). If you do, replace OneSignalSDKWorker.js in this guide with your filename.
2

Upload to your web server

Place OneSignalSDKWorker.js on your server so it is publicly accessible over HTTPS. The file must not require authentication or login to access.Recommended: Host the file in a dedicated subdirectory that never serves pages, such as /push/onesignal/. This avoids conflicts with other service workers on your site (e.g., a PWA or AMP service worker) and keeps the URL path stable.
  • Example: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
Alternative: The OneSignal Web SDK defaults to looking for the file at your site root (https://yoursite.com/OneSignalSDKWorker.js). You can upload the file to the root directory, but it may conflict with other service workers that need root scope. If you use a PWA, place OneSignalSDKWorker.js in a subdirectory instead.
Choose a permanent URL path. Once a browser registers a service worker at a given URL, changing that URL requires a migration.
3

Verify the file is accessible

Navigate to the file URL in your browser (e.g., https://yoursite.com/push/onesignal/OneSignalSDKWorker.js). You should see the importScripts line from the first step:
Browser displaying the single importScripts line inside OneSignalSDKWorker.js

Expected service worker file contents in the browser

If you see a 404 error, a blank page, or a login prompt, the file is not correctly uploaded or is behind authentication.
4

Tell the SDK where to find the file

The Web SDK looks for OneSignalSDKWorker.js at your site root (https://yoursite.com/OneSignalSDKWorker.js) unless you tell it a different location. How you tell it depends on your integration type.If you placed the file at your site root, no additional configuration is needed. Skip to the next step.If you placed the file in a subdirectory, you must set the path. Typical Site sets it in the dashboard. Custom Code sets it in OneSignal.init(). Mixing the two does not work: dashboard path fields do not apply to Custom Code, and serviceWorkerPath does not apply to Typical Site.

​
Typical Site

Set the path in the OneSignal dashboard. Do not pass serviceWorkerPath in code.
  1. Go to Settings > Push & In-App > Web.
  2. Under Advanced Push Settings, enable Customize service worker paths and filenames.
OneSignal dashboard fields for service worker path, filename, and registration scope

Service worker path configuration in the dashboard

See Web SDK setup for the Typical Site procedure.

​
Custom Code

Pass serviceWorkerPath and serviceWorkerParam in your OneSignal.init() call. Custom Code does not use the dashboard Customize service worker paths and filenames fields.
If the file is not at the site root and you omit these options, the SDK still fetches https://yoursite.com/OneSignalSDKWorker.js and registration fails.See Custom Code setup to add these options to your full init snippet.
5

Review service worker requirements

The OneSignalSDKWorker.js file must meet all of the following requirements for push notifications to work.
Service worker setup is complete.

Web SDK setup

Continue with the Web SDK setup guide for next steps.

​
Combining multiple service workers

Each service worker file on your site is registered at a scope — a URL path that determines which pages it controls. Only one service worker can be active at a given scope. If you already have a service worker (for example, a PWA or caching worker) and want OneSignal to share the same file, you can combine them.
Keeping service workers in separate files with separate scopes is simpler to maintain and avoids conflicts. Only combine them if your setup requires a single service worker file.
To combine, add the OneSignal importScripts line to your existing service worker file:
After combining, update the OneSignal configuration to point to your existing service worker file. Follow Tell the SDK where to find the file using the path and filename of your combined file.

​
Migration guide

This section is for existing OneSignal customers who need to change the service worker file path, filename, or scope. Do not follow these steps unless you have a specific reason to change your current configuration.
Reasons to migrate:
  • The root-scope OneSignal service worker conflicts with a Progressive Web App (PWA)
  • The service worker conflicts with AMP or another caching service worker
  • Security policies prohibit third-party service worker code at root scope
Option 1: Change scope only (recommended)Changing only the scope is the safest migration. The file stays at its current URL, so existing subscribers continue to receive notifications without interruption.If your file contains only OneSignal codeConfirm OneSignalSDKWorker.js contains only:
Update the scope using the dashboard (Typical Site) or serviceWorkerParam (Custom Code) as described in Tell the SDK where to find the file. No other changes are needed.
If OneSignalSDKWorker.js is not hosted at your domain root today, you must continue hosting it at its current URL with the Service-Worker-Allowed header for at least one year. Add a comment in your backend code or internal documentation so the file is not accidentally removed.
If your file contains OneSignal + other codeYour service worker may include additional importScripts calls (e.g., from following the combining multiple service workers guide). If your current setup still works, keep it as-is — splitting a merged service worker requires a two-phase rollout.If you must separate them:
1

Add a retention comment to the existing file

Above the OneSignal importScripts line in your current service worker, add:
Set the date at least one year in the future.
2

Create a new dedicated OneSignal service worker

Create OneSignalSDKWorker.js in a subdirectory (e.g., /push/onesignal/) containing only:
3

Update OneSignal configuration

Set the new path and scope using the dashboard (Typical Site) or OneSignal.init() (Custom Code) as described in Tell the SDK where to find the file.
4

Wait for subscribers to migrate

New and returning visitors automatically register with the new service worker. Wait at least one year for the majority of existing subscribers to revisit your site.
5

Clean up

Delete inactive users older than your chosen retention period, then remove the OneSignal importScripts line from the original service worker file.
Option 2: Change filename or file locationChanging the filename or directory is more complex because browsers fetch the service worker from the URL where it was originally registered. Subscribers who have not revisited your site still reference the old URL.
You must continue hosting the original file at its old URL for at least one year. Removing it causes 404 errors when the browser attempts to update the service worker, and affected subscribers stop receiving notifications.
If your file contains only OneSignal code
1

Add a retention comment to the old file

2

Create the new file at the new location

Place OneSignalSDKWorker.js (or your chosen filename) in the new directory with:
3

Update OneSignal configuration

Set the new path, filename, and scope as described in Tell the SDK where to find the file.
4

Wait for subscribers to migrate

New and returning visitors register with the new file automatically. Wait at least one year.
5

Clean up

Delete inactive users older than your retention period, then remove the old file.
If your file contains OneSignal + other codeFollow the steps in Option 1: Change scope only above. The process is the same.

​
FAQ

​
Does this guide apply to WordPress?

No. The WordPress plugin hosts and registers OneSignalSDKWorker.js in its sdk_files directory. Do not upload a worker to the site root or set serviceWorkerPath in code. See WordPress setup.

​
How do I set the service worker path for Typical Site vs Custom Code?

The Web SDK looks for OneSignalSDKWorker.js at your site root unless you set a custom path. Typical Site sets that path in the dashboard under Customize service worker paths and filenames. Custom Code sets it in code with serviceWorkerPath and serviceWorkerParam in OneSignal.init(). Dashboard path fields do not apply to Custom Code. See Tell the SDK where to find the file.

​
Why is my service worker returning a 404?

The file is not at the URL the SDK expects. Navigate to the full file URL in your browser to confirm it is accessible. If you placed the file in a subdirectory, the configured path must match the actual file location, including the directory and filename. Typical Site: check the dashboard path settings. Custom Code: check serviceWorkerPath in OneSignal.init().

​
Why are notifications not displaying after I moved the service worker file?

Existing subscribers still reference the old service worker URL. The browser fetches the registered URL (cached up to 24 hours) each time a push arrives. If the old URL returns a 404, those subscribers do not receive notifications. Continue hosting the old file for at least one year while subscribers naturally migrate by revisiting your site. See the migration guide and Web push notifications not shown guide.

​
Can I host the service worker on a CDN or subdomain?

No. Browsers require service workers to be served from the same origin as the page that registers them. The file must be on your primary domain — not a CDN, subdomain, or different domain.

​
Why does my PWA conflict with the OneSignal service worker?

Both are likely registered at root scope (/) and only one service worker can be active at a given scope. Move the OneSignal service worker to a subdirectory scope (e.g., /push/onesignal/) so your PWA retains control of root scope, or combine them as described in Combining multiple service workers.

​
Can I rename the OneSignalSDKWorker.js file?

Yes. If your server requires a specific naming convention (e.g., all lowercase), rename the file to something like onesignalsdkworker.js. Typical Site: update the Service worker filename field in the dashboard. Custom Code: update serviceWorkerPath in your OneSignal.init() call. See Tell the SDK where to find the file.

​
What content type should my server return for the service worker file?

The server must return Content-Type: application/javascript; charset=utf-8. Some servers or CDN configurations return an incorrect MIME type, which causes the browser to reject the service worker registration.