Guides
Log InSign Up

Web SDK setup

How to set up your website with OneSignal.

Suggest Edits

📘

This guide is for a typical site setup, not WordPress or Shopify

For common CMS integrations, see:

This guide will work on Frameworks Angular Setup, React JS Setup, and Vue JS Setup but allows manipulating the prompts in the OneSignal dashboard. To setup the prompts with code, see Custom Code Setup.

If you haven't already, sign up for a free account on onesignal.com.

If this is not your first app with OneSignal, click New App/Website. Otherwise, you will see the next page.

Name your app and organization something recognizable, then select Web from the platform list. You can set up more platforms later within the app's Settings page.

Click Next: Configure Your Platform.

1. Choose Integration

Select Typical Site. This will enable you to configure the prompts and other settings directly within the OneSignal dashboard.

2. Site Setup

Input your default site information.

1379

Image showing Site Setup step

FieldDescription
SITE NAMEThe default name for your site. Shows in push notifications.
SITE URLYour actual website URL (e.g. https://example.com, https://www.example.com).
Must include:

- https://
- If your site uses www make sure to include it.To test locally, see Local Testing Setup.
AUTO RESUBSCRIBE (HTTPS ONLY)Recommended: Allows push subscribers to automatically resubscribe upon returning to your site without being prompted if they clear their browser data or if you are transferring to OneSignal from another push provider.
DEFAULT ICON URLIcon used for Prompting and the default for push notifications.

Enter an https icon URL or upload file that is square 256x256 pixels.

The file must be .png, .jpg, or .gif.

3. Permission Prompt Setup

By default, the Push Slide Prompt will show on the first page view after 10 seconds. You can skip this step for now and come back later to add new prompts or modify this one. See our Web Prompting Guide for more details.

4. Welcome Notification (Optional)

A push notification sent immediately to current user upon subscribing to your site for the first time. Enabled by default, it can be toggled off to prevent showing and update message content at anytime. If you want to add a delay, toggle off this notification and use Journeys or Automated Messages.

5. Advanced Push Settings (Optional)

OneSignal provides several Advanced Options. For instance:

Multiple Service Workers

If you are using or plan to use another service worker on your site, please follow the OneSignal Service Worker Setup Guide.

Safari Certificate (Optional)

OneSignal automatically provides the necessary certificates to work with Safari Browsers at no additional cost. If you already have your own Safari Web Push Certificates, toggle on this option to upload your Safari Web .p12 Push Certificate and password.

1022

Click Save to continue.

6. Upload Files

Download OneSignal SDK file which is the Service Worker file. You must upload this file to your server.

Option 1. Create file and copy code

  1. Create a new file OneSignalSDKWorker.js and make it public.

  2. Copy-paste the following import statement into the file:

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

Option 2. Download zip folder and upload

  1. Click Download OneSignal SDK files (you can also download the file here).

  2. Unzip the download. There should be a single file you need to host.

Hosting the file

The OneSignal SDK file must be publicly accessible and can be placed at the top-level root of your site. The OneSignal SDK will look for the file at https://yoursite.com/OneSignalSDKWorker.js. If you want to place them in a subfolder, you can! Please see our OneSignal Service Worker Guide for instructions.

📘

Subfolders or Migrating from another Push Provider

If you want to place the OneSignalSDKWorker.js file in a subfolder or if you are migrating to OneSignal from another provider, please see our OneSignal Service Worker Guide for instructions.

🚧

Note regarding Service Worker file(s)

If you are revisiting this page for an existing site set up prior to November 22, 2021 and are currently using two service worker files:

  • OneSignalSDKWorker.js
  • OneSignalSDKUpdaterWorker.js

you should continue hosting both files. This is to prevent the Service Worker from going stale if a user doesn't return to your site in some time.

On November 22, 2021 the OneSignal Web SDK was updated to require only a single service worker file. New setups will now only require a single file.

7. Add Code to Site

To enable OneSignal on your site, you will need to paste the provided code into your website's <head>. If you do not have access to modify your site's code, you will need to contact a developer to help you.

The OneSignal JavaScript SDK code should work on any site, but if your site is setup using Angular, React JS, or Vue JS then follow these links.

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
    });
  });
</script>

8. Subscribe and Send Yourself a Notification

Go to your website. You should be prompted to subscribe to push notifications based on the prompt settings you setup. Click it to see the native browser prompt and subscribe to push. Then, Find & Set Test Subscriptions and send yourself a Push Notification.

👍

Setup Complete!

If you are having difficulty, please check Web Push Troubleshooting or contact [email protected] for assistance.

Updated about 2 months ago

What’s Next