Web SDK setup

​

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.

​

Configure your OneSignal app and platform

In the OneSignal dashboard:

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

Select integration type:

​

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.

​

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.

​

Permissions prompt

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

​

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.

​

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.

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

​

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.

​

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.

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.

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

​

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.

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

​

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

​

Set up test subscriptions

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

​

Send test push via API

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"
}'

​

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.

​

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.

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:

​

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.

​

Privacy & user consent

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:

• Data collected by the SDK
• Handling personal data

​

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:

• 🔁 Migrating to OneSignal from another service
• 🔌 Integrations
• 🛎️ Action buttons
• 🌐 Multi-language messaging
• 🛡️ Identity Verification
• 📊 Custom Outcomes

​

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.