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! See Migrating to OneSignal from another service 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:

1. An iPhone or iPad with iOS 16.4 or higher.
2. 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:

📘

Sending push notifications

See our Messages > Push guide for details on sending and designing push notifications or Templates for details on reusable push designs.

---

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): The amount of time a push notification will be held by the push services (FCM, APNS, HMS, etc) if the user's device is offline. Defaults to 3 days. Range: 0–2,419,200 seconds (28 days).

• Web Push Topic: By default, newer notifications replace (collapse) older ones for the same website if they haven’t been clicked. To display multiple notifications, set different web_push_topic values.

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!