Self Hosting the JavaScript Web SDK

Don't Host It Yourself If You Don't Need To

Users should almost always use our CDN-hosted version. OneSignal's JavaScript libraries are often updated to support new features, support browser changes, and to work around browser bugs or bugs in other software libraries.

We host this file on Cloudflare's international CDN with a 2 or 3 days browser cache duration. OneSignal is used widely enough that many users will already have this file in their browser cache when they visit a new client's website. In cases where we plan to make an update to it in the near future, we will temporarily lower the browser caching duration so that the previous version is promptly expired much sooner.

Technical Instructions if you wish to proceed with hosting the SDK yourself anyway

🔴 Please update your SDK version regularly. Releases more than a few weeks old may become incompatible.

• Web SDK releases are tagged by version (an incrementing integer) (e.g. v120085)
• Browse tags online using GitHub or through the Git command line tool. When browsing online, select the latest tag and download the source
• The release should be available in <repository root>/dist
• See the README.md file in <repository root>/dist, and the instructions below

HTTPS Web Push Integrations

1. Download the following files

   • https://cdn.onesignal.com/sdks/OneSignalSDK.js
   • https://cdn.onesignal.com/sdks/OneSignalPageSDKES6.js
   • https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js

2. Open OneSignalSDK.js and find https://cdn.onesignal.com/sdks/ and replace with your domain.

3. When referencing the OneSignal SDK on your webpages, replace:

   <script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async="async"></script>

   with your own copy, e.g.:

   <script src="https://yoursite.com/assets/OneSignalSDK.js" async="async"></script>

4. Modify OneSignalSDKWorker.js, replacing:

   importScripts('https://cdn.onesignal.com/sdks/OneSignalSDK.js');

   with your own copy. Any valid URL (a relative URL to your site, an absolute URL to a CDN) is fine here, e.g.:

   importScripts('https://yoursite.com/assets/OneSignalSDK.js');

   • The file OneSignalSDKWorker.js should still:

     • Have the same file name
     • Be accessible from the root of your site, and not a subfolder

     If you'd like to move the worker file locations, please see Can the worker files be served from a subfolder of my site?.