Web SDK setup

​

Overview

​

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

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

​

Site setup

• 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, a bell icon is used as the default.

​

Site URL

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

​

Local testing

Localhost configuration

Set the SITE URL to exactly match your localhost environment URL. The URL must match one of these common localhost formats:

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

​

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.

Copy

Ask AI

  <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

​

Welcome notification (optional)

​

Advanced settings

​

Webhooks

​

Service workers

• Path to service worker files is the path to the directory where you will host the service worker file.
• Main and Updater service worker filenames defaults to OneSignalSDKWorker.js. You can rename this file, but it must use a .js extension.
• Service worker registration scope controls which pages the service worker can operate on. For push notifications this has no effect. Set it to the same path as your service worker file location.

​

Click behavior

​

Persistence

​

Safari certificate (Optional)

​

Upload service worker file

​

Add code to your site

  <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

​

Testing the OneSignal SDK integration

​

Check web push subscriptions

1

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.

2

Check your OneSignal dashboard

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

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

1

Add to Test Subscriptions.

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

2

Name your subscription.

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

3

Create a test users segment.

Go to Audience > Segments > New Segment.

4

Name the segment.

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

5

Add the Test Users filter and click Create Segment.

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

​

Send test push via API

1

Get your App API Key and App ID.

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

2

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 created earlier.

Copy

Ask AI

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

3

Run the code.

Run the code in your terminal.

4

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.

5

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.

Push notification message reports

View delivery, click, and conversion stats for your push notifications.

• The API request and response (copy-paste into a .txt file)
• Your Subscription ID
• Your website URL with the OneSignal code

​

User identification

​

Assign External ID

​

Add data tags

​

Add email and/or SMS subscriptions

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

​

Privacy & user consent

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

​

Listen to push, user, and in-app events

​

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

​

Web SDK setup & reference

​

FAQ

​

Does web push work on HTTP sites?

​

Why do I need a service worker file?

​

Can I use web push on iOS (iPhone/iPad)?

​

Why are my notifications not showing?