Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to manage web push subscriptions and how subscription status is affected by both user action and browser behavior.

​
Understand push permissions

Users must give your website permission to send them push notifications. It is not possible to receive push notifications without explicitly granting the site permission using the system-level permission prompt.
Permissions can be either:
  • Default: permission has not been granted to denied.
  • Granted: you allowed the website to send you notifications.
  • Denied: you blocked the website to send you notifications. This can be a temporary block if you clicked the x to close the prompt repeatedly or a permanent block if you clicked Block or toggled off permission in the browser settings.
For more details on the native system-level permission prompt and/or any of the OneSignal prompts, see Web permission prompts.

​
How to unsubscribe from web notifications

You can unsubscribe from web push notifications in three ways:

​
Unsubscribe within browser settings

You can manage or remove notification permissions directly in browser settings. Here are quick-access URLs and official docs to learn more: On these pages, just click the options to remove or block the website(s) you don’t want notifications from.

​
Unsubscribe while on the website

Reset permission Most browsers have a “lock” or “settings” icon next to the URL. Clicking it reveals site-specific permissions where users can disable push notifications.
OneSignal prompts If the website contains the OneSignal Bell Prompt or Custom Link prompt users can unsubscribe directly via those UI elements and be able to resubscribe using the same as desired.

​
Deleting browser data, clearing cookies and site data

If you delete history and/or delete your cookies and site data, it will temporarily prevent notifications from showing. However, if you don’t remove push permissions from the site, you may be automatically re-subscribed and start getting notifications again upon returning to the site.

​
How to test your permission prompts

These steps explain how to test your prompt and subscription flow like a first time visitor.
1

Visit your site with the OneSignal SDK setup.

Do not use an incognito, private, or guest browser setting. This example uses Chrome version 135 on macOS but the flow should be relatively the same for most browsers.
2

Reset push permissions

Click the site settings or lock icon next to the site URL and select Reset permission or remove permissions for Notifications. Skip to the next step if you don’t see this permission option.
3

Delete site data.

Click Cookies and site data > Manage on-device site data or follow the browser’s flow to see your site’s data option.
Delete the data for your site and exit the settings to get back to your site.
4

Open your developer tools.

Usually you can just right click the screen and press Inspect.
5

Follow the steps needed to prompt for push notifications and on the required system-level permission prompt, select "Allow".

If you do not see the prompt or don’t know the steps, see Web permission prompts.
6

Check the console for any errors.

If you see anything in red related to OneSignal, see our Web SDK troubleshooting docs.
7

Get subscription ID

In the Console type or copy-paste this code: OneSignal.User.PushSubscription.id
  1. This will log your OneSignal subscription ID. Copy-paste this into your OneSignal Dashboard Audience > Subscriptions tab.
  2. If a subscription ID was not logged in the console, then you are not successfully subscribed. Please see Web SDK troubleshooting for details.
8

Next to the subscription, select the 3-dot options button and "Add to Test Users". Then name and date the test user so it is recognizable."

9

Navigate to Messages > Push > New Message > New Push and on the Push create form add a Message.

See Push for more details if needed.
10

Select "Test & Preview", find and check your test user, then click "Send Test Push".

11

You should receive the push you tested.

If you did not receive a push, see Web push: Notifications not shown for further debugging.
You have successfully setup web push with OneSignal. Next steps:

​
Receiving Notifications When the Browser is Closed

Browsers behave differently across platforms. Please refer to the table below for support for receiving notifications even when the browser is closed.
Browser NameAndroidWindowsmacOS
Chrome / ChromiumYesYesNo
FirefoxYesYesNo
SafariN/AN/AYes
OperaYesYesNo
EdgeYesYesNo
Chrome - Chrome runs as a background process by default even when all the windows are closed. As long as the background process is running, notifications will still be received. If the Chrome background process is not running, notifications will not be received. Firefox - On Mac OS X, the process still exists even if windows are closed, and a notification can be received if all windows are closed (as long as there is still a dot in the dock showing Firefox is still running). On Windows, the process exits after all windows are closed so notifications cannot be received unless a Firefox window is still open. Safari - Safari does not have to be running to receive notifications, as they are sent directly to the operating system. The user still has to sign up for Safari web notifications, but after that they will be received even when Safari is completely closed. Subscribers have up to 3 days to retrieve the last known missing notification before messages expire permanently. For example, suppose a subscriber was supposed to receive a Firefox web push notification, but Firefox was closed. If the subscriber opens Firefox within 3 days, the subscriber will receive only the last known web push notification that didn’t expire. If the subscriber opens Firefox after 3 days, the web push notification sent more than 3 days ago will not be received.