Web Push notifications are a great way to get your users' attention and share important information when they are not actively using your website. They can display text, images, buttons, play sounds, and more!

For web push notifications to work, you need an HTTPS single-domain site origin. You must ask for and users must grant permission to receive your notifications. This creates unique device identifier for your site and the user's browser profile. Web push is supported across most browsers and devices; however, users can't subscribe to websites while in Incognito or private browser mode. For more details, see Web Push FAQ.

This guide will walk you through setting up web push notifications with OneSignal, including integrating our SDK into your website, configuring necessary settings, and testing your setup to ensure everything works seamlessly. By the end of this setup process, you'll be able to send personalized and targeted push notifications to your users, helping to improve retention, boost user engagement, and achieve your business goals.

Migration to OneSignal from other provider

If you are moving to OneSignal from another service and already have web push notifications setup, then migration should be quick! Follow the below migration steps and continue on with the setup guide.

Migration steps (click to expand)

Evaluate your current provider setup.
1. Audit your current push provider’s setup (e.g., platforms supported, messaging history, API usage).
Configure your site to replace the current provider's code with OneSignal.
1. Web push requires Service Workers. You can have multiple service workers for your site, but should remove and unregister your current provider's service worker to prevent conflicts. See OneSignal Service Worker for details.
2. More details to follow in our Web SDK setup guide.
Migrate User and Subscription data.
1. Active web push users will automatically and silently be added to OneSignal when they return to your site with the OneSignal code setup.
2. You cannot import your current web push users in OneSignal. See Subscriptions for details.

Activate web platform

Within your OneSignal app, go to Settings > Push & In-App and Activatethe web platform.

From here, choose the type of integration you need:

Typical Site (Recommended): Allows you to control and update the prompts within the OneSignal dashboard without writing additional code.
WordPress Plugin: Required if using WordPress and our WordPress plugin.
Custom Code: For developers who want more control over the prompts and configuration. Allows you to control the prompts using our SDK on the site instead of through the dashboard.

Site setup

Next, add your site details:

Site Name: This is used as the default title of your web push notifications if no title is provided.
Site URL: This must be the exact origin (URL) of your site. For example, if your site is https://mydomain.com, don’t use https://www.mydomain.com. Follow the Same-origin policy for more details.
Local Testing: Developers, refer to our Local Testing Guide if you are testing on localhost.
Auto Resubscribe (Recommended): Allows users who clear their browser data/cache to be automatically resubscribed when they return to your site. They will not be prompted again unless they turn off push permissions.
Default Icon URL (Recommended): This icon is used for web push notifications and prompts. It should be a square 256x256 px PNG or JPG file.

Permission prompt setup

This is where you setup the web push prompt for Typical Site and WordPress setup. If using Custom Code you can press Save at the bottom and jump to Web SDK setup.

📘
Ask users for permission to send web push
See Web Permission Prompts for details on setting up and designing your web push prompts.

Welcome notification

Send a push immediately after the user subscribes to the website the first time. This is a good opportunity to thank them for subscribing and gives the user an example of how web push notifications work.

Web SDK setup

Developer handoff! Now its time to add the OneSignal SDK and service worker to your website. These next steps require access to your website's code and server. Don't forget to invite your developer as an admin role if you need assistance!

🔨
Developers: Web SDK setup docs
Follow our Web SDK setup to add the necessary code to your site.

While you wait for your developer to finish setting up the SDK, you can click Save and Finish to exit the web configuration dashboard and continue following the steps below.

Users & web push subscriptions

As users subscribe to push notifications on your website with the OneSignal SDK active, a Subscription record and a User record is created for that device and browser profile.

Web push subscriptions are created when users:

Subscribe to push notifications on your website with a specific device and browser profile. Incognito and private browser mode does not work.
Clear browser data (cache/cookies) and return to your site with Auto resubscribe enabled.

Users are considered anonymous until you set your own External ID to identify the user across all their subscriptions.

📘
Users, subscriptions, & segments
Please review our Users and Subscriptions docs for more details.
Once you start accumulating users, you can group them into Segments.

Web push for iOS

Apple started supporting web push notifications on iPhones and iPads running iOS 16.4+. This has a few technical requirements outlined in the Web SDK setup but also requires your users to have the following:

An iPhone or iPad with iOS 16.4 or higher.
Added your web app to their device's Home Screen.

Details on Getting Your Audience to "Add to Home Screen" can help increase your web push subscription rate for iPhone and iPad.

Design web push notifications

Customize your notifications by adding titles, messages, icons, and images following these guidelines:

1. Title

The top-most customizable text of the notification. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 60-80 character limit.
Supports: Emojis 👍, Message Personalization, Language & Localization

2. Message

The localized text the provides the notification's main content. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 150 characters limit.
Supports: Emojis 👍, Message Personalization, Language & Localization

3. Icon

The best way for users to recognize your site.

Recommended size: 256x256 px.
Supports PNG, JPG, and GIF (not animated).

4. Large image

An additional large image you can include for Chrome web push subscriptions for Windows and Android only (macOS doesn't support large images and just expands the icon).

Recommended size is 2:1 aspect ratio like 480x240 px.
- Avoid images wider than 2,000 pixels.
- Keep the image size under 1 MB.
Supports PNG, JPG, and GIF (not animated).

5. Action buttons

Customizable buttons (supported on Chrome).

See Action Buttons for details.

6. Badge & browser

The badge is the small icon that shows in the Android status bar and is customizable on some versions of Chrome.

Must be an alpha-channel icon PNG. Example Badge icon.
Size 72x72 pixels

7. Domain

Set by the browser. The website origin to which the device is subscribed.

8. Timestamp & dismiss buttons

Set by the device when the message was received.

9. More Options

Set by the browser. Includes notification settings and focus assist.

Configure notification behavior

You can control how web push notifications behave after they're sent, including their lifespan on push servers when a device is offline, notification collapsing, and click actions.

Display behavior

Web push notifications will pop up on the user's screen based on their operating system's notification settings and browser configurations. Browsers do not support custom sounds for web push notifications.

Removing notifications from view

Time To Live (TTL):
Specifies how long a push notification is stored on the FCM/APNS/WNS servers if the user’s device is offline. Once the TTL expires, the notification is removed.
See Remove Notifications and TTL for more details.
Topics & Collapsing:
By default, newer notifications replace (collapse) older ones for the same origin if they haven’t been clicked. To display multiple notifications, set different web_push_topic values.
See Web Push Topic & Collapsing for more information.

Click behavior

By default, clicking a notification will open your website. However, you can customize this behavior to open any desired URL.

More customization options are available in Advanced Options.
If you don’t want to link to any page, add ?_osp=do_not_open to the URL. For example:
https://yoursite.com/page?_osp=do_not_open. This will prevent the notification from redirecting to any page and will dismiss it when clicked.

🔨
Developers: Setup your deep links to work with push!
Deep linking allows you to direct users to specific pages of your app to take action, such as making a purchase on a checkout page!
Deep linking can be complicated because there are multiple ways to set it up. For details, see our Deep Linking guide.

👍
Send your push messages!
You should now be setup and ready to send push notifications to your web push subscribers.
See our Push guide to get started!

Web push setup

Migration to OneSignal from other provider