Web SDK setup - OneSignal

Overview

Web push notifications let you send real-time updates, reminders, and personalized messages to your users, improving engagement and retention. OneSignal supports all major browsers and platforms, letting you write once and deliver across: Chrome, Firefox, Edge, Safari, and other supported browsers.

Requirements

HTTPS website: Web push does not work on HTTP or in incognito/private modes.
Server access: You’ll need to upload a service worker file to your site.
Single origin: Web push follows the Same-origin policy. If you have multiple origins (domains/subdomains), you will need multiple OneSignal apps (one per origin). To comply with this browser limitation, you can either:
- Redirect traffic to a single origin for subscriptions.
- Create multiple OneSignal apps—one per origin.

If your team already created an account with OneSignal, ask to be invited as an admin role so you can setup the app. Otherwise, sign up for a free account at onesignal.com to get started!

Configure your OneSignal app and platform

In the OneSignal dashboard:

Go to Settings > Push & In-App > Web.

Activate the web platform in your OneSignal settings

Select integration type:

Typical Site (recommended)

Manage prompts and settings directly through the OneSignal dashboard without additional coding.

WordPress

Required if using WordPress with our official plugin.

Custom Code

For developers who need full control over prompts and SDK configuration.

Site setup

Add the site details:

Site Name: The name of your site and default notification title.
Site URL: The URL of your site. See Site URL for more details.
Auto Resubscribe: Enable this to automatically resubscribe users who clear their browser data when they return to your site (no new permission prompt required)
Default Icon URL: Upload a square 256x256px PNG or JPG image that appears in notifications and prompts. If not set, we use a bell for the default icon.

Web settings in the OneSignal dashboard

Site URL

Enter the exact origin of your site, e.g., https://yourdomain.com. Avoid using www. if your site isn’t configured that way. If you have multiple origins:

Redirect to a single origin.
Or set up one OneSignal app per origin.

Local testing

Our web SDK can be tested on localhost environments. If you are testing on localhost, we recommend setting up a different OneSignal app other than your production app.

Localhost configuration

Set the SITE URL to exactly match your localhost environment URL. It must be a common localhost URL, examples:

http://localhost
https://localhost:3000
http://127.0.0.1
https://127.0.0.1:5000

If your localhost is using HTTP, select Treat HTTP localhost as HTTPS for testing.Google Chrome treats http://localhost and http://127.0.0.1 as secure origins, allowing HTTPS integrations even on HTTP. This is why you cannot test other non-standard origins on HTTPS localhost.

Local testing in the OneSignal dashboard

Add `allowLocalhostAsSecureOrigin` to your OneSignal `init` options

When initializing OneSignal on your localhost site, add allowLocalhostAsSecureOrigin: true, to your OneSignal init options.Additionally, if you’re testing localhost on HTTPS with a self-signed certificate, you may have to ask Chrome to ignore invalid certificates for testing with: --allow-insecure-localhost. Firefox and Safari provide built-in mechanisms to add exceptions for security certificates.

html

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

Permissions prompt

Typical site setup allows you or your teammembers to add, remove, and update permission prompts through the OneSignal dashboard anytime.

For details on the permission prompts, see Web Permission Prompts.

Welcome notification (optional)

You can also set a welcome notification to be sent to users when they subscribe to push notifications.

Advanced settings

Additional features configurable in the OneSignal dashboard.

Webhooks

Our web SDK provides the ability to POST certain web push events to a URL of your choosing. Web Push Webhooks are a separate implementation from Event Webhooks and cannot be used interchangeably.

See Web Push Webhooks for more details.

Service workers

On the next page of web push configuration, you will be provided the OneSignalSDKWorker.js service worker file. Our web SDK defaults to look for this file in the root of your site. If you want to change our service worker file location, name, and/or scope, this is where you can update those settings.

Path to service worker files is path to the directory you will put these files.
Main and Updater service worker filenames can just be OneSignalSDKWorker.js or if you want to rename this file. Must use .js file extension.
Service worker registration scope are the pages this file can work on. For push notifications, this doesn’t matter and was originally designed for cases where you want to add more functionality to the service worker file. You should set this as the same path as your location.

Service worker configuration

With this example, you should see the file’s code publicly accessible at https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js

See OneSignal Service Worker for more details.

Click behavior

Control how users navigate to the URL you set when they click the notification.

If users do not have your site open on any browser tabs, and click on a notification that takes them to your site, the browser will open a new tab and navigate to the notification’s URL.
If users do have your site open on one or more browser tabs, and click on a notification that takes them to your site, there are several possible ways the browser can behave that you can configure:
- Exact Navigate (default) - If the notification’s exact URL (e.g. example.com/product) matches a tab that the browser already has open, the browser will navigate to the notification’s URL in that tab.
- Origin Navigate - If the notification’s origin (e.g. example.com) matches a tab that the browser already has open, the browser will navigate to the notification’s URL in that tab.
- Exact Focus - If the notification’s exact URL (e.g. example.com/product) matches a tab that the browser already has open, the browser will focus on that tab, but not refresh the page.
- Origin Focus - If the notification’s origin (e.g. example.com) matches a tab that the browser already has open, the browser will focus on that tab, but not refresh the page.

Persistence

The default web push behavior is they pop-up on the device for roughly 5 seconds before they are moved to the Notification Center where they are kept for about 1 week before being removed by the operating system. Some devices and versions of Chrome and Edge allow you to persist notifications for longer on the screen. This means the notification will stay on the screen until the user interacts with it. This might annoy your users and is not recommended. Also, if you enable persistence it will affect how notifications appear to subscribers by reducing character count and may affect how images and buttons are displayed. When changing them, they will go into effect only for subscribers that visit the site with the updated settings. If you do not see these options change, you will either need to wait

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.

Safari certificate configuration

Upload service worker file

As discussed briefly above in the Advanced settings > Service workers we will add the OneSignalSDKWorker.js Service Worker file to your site.

Upload service worker file step

If you did not set the Path to service worker files in the Advanced settings > Service workers section, you will need to place the OneSignalSDKWorker.js file in your site’s top-level root. Otherwise, you will need to place it in the directory you set.

Create a new file called OneSignalSDKWorker.js and make it public.
Copy-paste the following import statement into the file:

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

Once the file is on your server, check the following to make sure it works:

Verify the location

Make sure the file is located in the same Path to service worker files as set in Advanced settings > Service workers. If you did not update these settings, then you should have put the file in your root. For example:

https://yourdomain.com/OneSignalSDKWorker.js
https://yourdomain.com/some-subdirectory/OneSignalSDKWorker.js

It must be publicly accessible on your origin

The OneSignalSDKWorker.js file must be publicly accessible and available on your origin. It cannot be hosted via a CDN or placed on a different origin with redirect.When you visit the URL to the file, you should see the code.

It must be served with a content-type: application/javascript

This is a javascript file and needs to be served as such. It cannot have a content-type of text/html.

If you have additional questions or migrating to OneSignal from a different web push provider, it is recommended to review our OneSignal Service Worker docs.

Add code to your site

You should now be all set to add our SDK to your site. Our JavaScript SDK code provided should work on any site, but if your site is setup using Angular, React JS, or Vue JS then follow these links. To initialize OneSignal on your site with our JavaScript SDK, copy/paste the provided code into your website’s <head> tags. Our dashboard will provide the following code but includes your OneSignal app ID.

JavaScript

  <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>

iOS web push support

Apple started supporting web push notifications on iPhones and iPads running iOS 16.4+. Unlike Android devices where web push just “works” as long as visited on a supported browser, Apple added a few more requirements for web push to work on iPhones and iPads:

Web Application Manifest

Add the required manifest.json file properties to your site.

Getting Your Audience to 'Add to Home Screen'

Helpful tip for getting your iOS visitors to add your site to their home screen.

Mobile Web Push for iOS/iPadOS

Full setup details, testing and troubleshooting.

Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

Check web push subscriptions

Launch your site on a test device.

Use Chrome, Firefox, Edge, or Safari while testing.
Do not use Incognito or private browsing mode. Users cannot subscribe to push notifications in these modes.
The prompts should appear based on your permission prompts configuration.
Click Allow on the native prompt to subscribe to push notifications.

Web push native permission prompt

Check your OneSignal dashboard

Check the OneSignal dashboard:

Go to Audience > Subscriptions.
You should see a new entry with the status Subscribed.

Dashboard showing subscription with 'Subscribed' status

You have successfully created a web push subscription. Web push subscriptions are created when users first subscribe to push notifications on your site.

Set up test subscriptions

Test subscriptions are helpful for testing a push notification before sending a message.

Add to Test Subscriptions.

In the dashboard, next to the subscription, click the Options (three dots) button and select Add to Test Subscriptions.

Adding a device to Test Subscriptions

Name your subscription.

Name the subscription so you can easily identify your device later in the Test Subscriptions tab.

Dashboard showing the 'Name your subscription' field

Create a test users segment.

Go to Audience > Segments > New Segment.

Name the segment.

Name the segment Test Users (the name is important because it will be used later).

Add the Test Users filter and click Create Segment.

Creating a 'Test Users' segment with the Test Users filter

You have successfully created a segment of test users. We can now test sending messages to this individual device and groups of test users.

Send test push via API

Get your App API Key and App ID.

In your OneSignal dashboard, go to Settings > Keys & IDs.

Update the provided code.

Replace YOUR_APP_API_KEY and YOUR_APP_ID in the code below with your actual keys. This code uses the Test Users segment we created earlier.

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

Run the code.

Run the code in your terminal.

Check images and confirmed delivery.

If all setup steps were completed successfully, the test subscriptions should receive a notification.

Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.

Expanded push notification with image on Chrome macOS

Check for confirmed delivery.

In your dashboard, go to Delivery > Sent Messages, then click the message to view stats.You should see the confirmed stat, meaning the device received the push.

Safari does not support Confirmed Delivery.

Delivery stats showing confirmed delivery

If you’re on a Professional plan or higher, scroll to Audience Activity to see subscription-level confirmation:

Confirmed delivery at the device level in Audience Activity

You have successfully sent a notification via our API to a segment.

Need help? Contact support@onesignal.com with the following information:

Copy-paste the API request and response into a .txt file
Your Subscription ID
Your website URL with the OneSignal code

We’ll be happy to help!

User identification

Previously, we demonstrated how to create web push Subscriptions. Now we’ll expand to identifying Users across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We’ll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for Integrations). Set the External ID with our SDK’s login method each time they are identified by your app.

OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

Add data tags

Tags are key-value pairs of string data you can use to store user properties (like username, role, or preferences) and events (like purchase_date, game_level, or user interactions). Tags power advanced Message Personalization and Segmentation allowing for more advanced use cases. Set tags with our SDK addTag and addTags methods as events occur in your app. In this example, the user reached level 6 identifiable by the tag called current_level set to a value of 6.

A user profile in OneSignal with a tag called "current_level" set to "6"

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

Segment editor showing a segment targeting users with a current_level value of greater than 4 and less than 10

Screenshot showing a push notification targeting the Level 5-10 segment with a personalized message

Add email and/or SMS subscriptions

Earlier we saw how our SDK creates web push subscriptions to send push. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

Use the addEmail method to create email subscriptions.
Use the addSms method to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates. You can view unified users via Audience > Users in the dashboard or with the View user API.

A user profile with push, email, and SMS subscriptions unified by External ID

Best practices for multi-channel communication

Obtain explicit consent before adding email or SMS subscriptions.
Explain the benefits of each communication channel to users.
Provide channel preferences so users can select which channels they prefer.

To control when OneSignal collects user data, use the SDK’s consent gating methods:

setConsentRequired(true): Prevents data collection until consent is given.
setConsentGiven(true): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes. The SDK provides several event listeners for you to hook into. See our SDK reference guide for more details.

Push notification events

Click event listener: Detect when a notification is tapped.
Foreground lifecycle listener: Control how notifications behave in foreground.

User state changes

User state change event listener: Detect when the External ID is set.
Permission observer: Track the user’s specific interaction with the native push permission prompt.
Push subscription change observer: Track when the push subscription status changes.

Advanced setup & capabilities

Explore more capabilities to enhance your integration:

Web SDK setup & reference

Make sure you’ve enabled all key features by reviewing the Web push setup guide. For full details on available methods and configuration options, visit the Web SDK reference.

Congratulations! You’ve successfully completed the Web SDK setup guide.

Need help?Chat with our Support team or email support@onesignal.comPlease include:

Details of the issue you’re experiencing and steps to reproduce if available
Your OneSignal App ID
The External ID or Subscription ID if applicable
The URL to the message you tested in the OneSignal Dashboard if applicable
Any relevant logs or error messages

We’re happy to help!

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

​Overview

​Requirements

​Configure your OneSignal app and platform

Typical Site (recommended)

WordPress

Custom Code

​Site setup

​Site URL

​Local testing

​Permissions prompt

​Welcome notification (optional)

​Advanced settings

​Webhooks

​Service workers

​Click behavior

​Persistence

​Safari certificate (Optional)

​Upload service worker file

​Add code to your site

​iOS web push support

Web Application Manifest

Getting Your Audience to 'Add to Home Screen'

Mobile Web Push for iOS/iPadOS

​Testing the OneSignal SDK integration

​Check web push subscriptions

​Set up test subscriptions

​Send test push via API

​User identification

​Assign External ID

​Add data tags

​Add email and/or SMS subscriptions

​Privacy & user consent

​Listen to push, user, and in-app events

​Push notification events

​User state changes

​Advanced setup & capabilities

​Web SDK setup & reference

Overview

Requirements

Configure your OneSignal app and platform

Site setup

Site URL

Local testing

Permissions prompt

Welcome notification (optional)

Advanced settings

Webhooks

Service workers

Click behavior

Persistence

Safari certificate (Optional)

Upload service worker file

Add code to your site

iOS web push support

Testing the OneSignal SDK integration

Check web push subscriptions

Set up test subscriptions

Send test push via API

User identification

Assign External ID

Add data tags

Add email and/or SMS subscriptions

Privacy & user consent

Listen to push, user, and in-app events

Push notification events

User state changes

Advanced setup & capabilities

Web SDK setup & reference