Learn how to integrate, configure, and migrate the OneSignal Service Worker for Web Push Notifications.
How service workers work
OneSignalSDKWorker.js
file from the OneSignal dashboard or Download the OneSignal Service Worker File here.
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.
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:
content-type
of application/javascript; charset=utf-8
.https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
then the path is: /push/onesignal/
.js
filename, which contains the OneSignal importScripts
line. If you did not change the file name, this will be: OneSignalSDKWorker.js
If your server forces files to have lowercase, you can set the filename to be onesignalsdkworker.js
/push/onesignal/
and scope could be the same path or deeper like: /push/onesignal/js/
OneSignalSDKWorker.js
file to a different path or
scope./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.
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.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.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.