Web Prompting Overview

"Prompting" is asking users for permission to send them push notifications. Prompts are pop-up messages presented by the browser or mobile app and require the user to click "Allow" to be subscribed.

If you have a mobile app, see our iOS Prompt Guide. Android Mobile App devices don't need to be prompted, they get subscribed when opening your app for the first time.

Web Push works on Desktop and Android. Apple does not support web push on iOS like iPhone and iPad. Browsers provide their own Native Permission Prompt, which is required to be both shown and clicked "Allow" for the user to subscribe to your website.

Browsers now highly recommend websites be more selective when it comes to showing the Native Permission Prompt. This is why using OneSignal Prompts or your own custom "soft prompts" before the native prompt is encouraged.

---

OneSignal Prompts

OneSignal provides "soft prompts" that are shown before the Native Permission Prompt and engage the user to select categories they are interested in getting messages about and provide phone or email. These prompts do not replace the native prompt and do not subscribe the user to web push.

These prompts are beneficial because they increase the likelihood users will stay subscribed to your messages and are highly recommended by the browsers. Permission prompts do three things:

1. Inform a user of the value of subscribing to Push Notifications, Email and SMS
2. Prevent users from being blocked from subscribing.
3. Trigger a Native Prompt, if users indicate intent.

OneSignal Prompts are a 'soft request', meaning that they are not invoking the 'hard request' of the browser's Native Permission Prompt. This is important because if a user denies the native prompt, the developer is unable to prompt the user again, unless the user goes through a multi-step process to re-enable these permissions. On the other hand, if a user dismisses a Soft Prompt, the app or website can still present them the option later on.

Slide Prompt

The Slide Prompt displays on top of your site, in the top center of the browser (bottom center on Android).

Category Slidedown

The Category Slidedown works just like the regular Slide Prompt except it also allows subscribers to opt-in or out of notification categories. The Category Slidedown is configurable through the dashboard for Typical Site setup and can also be configured via custom code.

Email & Phone Number Web Prompt

The Email & Phone Number Slidedown adds optional text fields for users to add email, phone number or both. The Category Slidedown is configurable through the dashboard for Typical Site setup and can also be configured via custom code.

Subscription Bell

The subscription bell is a small widget that resides in the lower left or right corner of your site, which users can click to bring up the Native Permission Prompt for your site. It is designed to be small enough that you may keep it on your site at all times, and does not require users to dismiss it.

Custom Link

Simply add a snippet to your site's markup and it will be rendered as a button or link that triggers subscription flow when user chooses to subscribe. Provides good user experience. Can be customized through the dashboard at any time without changes to your site's code.

Native Permission Prompt

HTTPS sites may choose not to use a soft prompt and instead trigger the browser's Native Permission Prompt. However, immediately prompting users to subscribe with the Native prompt is being deprecated by the browsers and is not recommended.

---

Delayed Prompts

Best practice is to delay the Slide or Native Prompt from showing on screen. Giving visitors time to browse your content before prompting can improve engagement and ensure the browser doesn't penalize your site.

You can delay prompts based on:

• page views: the number of times a page is viewed/loaded on the screen
• seconds: amount of time passed in a single page to show the prompt

📘

Programmatically show the prompt anytime!

Use our SDK Prompting Methods to show the prompt with code.

Make sure to turn off the "Auto-prompt" option to call these methods.

Using the Typical Site Setup you can customize showing the Slide or Native prompt after X amount of seconds the user is on the site and/or after X amount of page views. For example, show the prompt 30 seconds after the user visits 3 pages.

If using Custom Code Setup, see examples for configuring prompt delays through OneSignal init.

WordPress requires some more steps shown in this guide on adding a delay to your WordPress Site.

---

FAQ

After dismissing a web push prompt, when is the prompt shown again?

If a user clicks "Block" (Chrome), "Don't Allow" (Safari), or "Never Allow" (Firefox) on the Native Permission Prompt they can never be prompted from the site again and must subscribe or reset permissions through a multi-step process through the browser settings. This is one reason it is recommended to use the OneSignal Prompts.

If a user clicks "X" on the Native Permission Prompt or "No" on the OneSignal Prompts, then the following occurs:

Native Permission Prompt:

Chrome - You have 3 tries to get the user to subscribe, after the 3rd "X" click on the required native permission prompt, they will not get prompted again for a week. More on this Chrome feature here. For Chrome on Android, see Why is Slide Prompt Showing on Mobile.

Firefox - Beginning with Firefox 70 once a user clicks "X" they will need to click the small notification icon in the browser to be prompted again. Also, with Firefox 72+ the Native Browser Prompt is prevented from showing, see below Why do I see the Slide Prompt on Firefox when I want the Native Browser Prompt for more details.

OneSignal Soft Prompts:

The OneSignal Side Prompt will show after 3 days, 7 days, then 30 days if the user clicks "Allow" or "Cancel" on it and is still not subscribed.

For instance, if a user clicks "Allow" on the slide prompt, but "x" on the native prompt, it will not show again for 3 days the first time. After 3 days, it will show again and if the user clicks "Cancel" or "Allow" but "X" on the native prompt, it will not show again for 7 days. After 7 days if the user does this again, it will be every 30 days.

If the user clears cookies or browser data, the cycle resets.

For testing purposes, please follow Clearing your cache and resetting push permissions to access your site as a new first-time user.

What are some best practices around Web Push Prompting?

It is best to ask visitors to subscribe after you have provided some value to them through the site. This could be after they have read your articles or in a "site settings"/"profile" page, and/or in your shopping-cart or check-out flow.

Common best practices include:

1. Using a Delayed Slide Prompt.
2. Embedding the Custom Link Prompt in the middle and/or at the end of the articles and within a "Subscription Page" or section of the user's Profile page if you have one.
3. Adding the Bell Prompt to allow users to easily subscribe/unsubscribe throughout the site.
4. If you add your own call-to-action buttons (like add to cart or subscription events) on the site or want to show the Native Browser Prompt anytime, use the OneSignal.showNativePrompt(); method. Your site must be HTTPS and did not select "My site is not fully HTTPS" in the OneSignal Site configuration.

How can I translate the OneSignal Prompts?

You can put any language you like into the prompt. If you are trying to dynamically change the prompt language based on the page, then switch to the Custom Code Setup and initialize OneSignal based on the language of the page.

Currently OneSignal does not automatically translate the Slide Prompt , Bell Prompt , or Custom Link prompt. They default to English, but you can put any language and message you want.

The Native Browser Prompt will automatically translate to the browser language settings.

Can I AB Test Prompts?

Using the Custom Code Setup you can initialize OneSignal with the different prompting options. You would need to setup your own way to trigger the A/B/C/D etc tests which initialize OneSignal.

As a bonus, you can use the Subscription Change method to detect when the user subscribed and add Data Tags based on which test won the subscription.

Why does my Prompt keep showing up?

Make sure you are not in incognito mode, private browser mode or guest browser mode.

Can I segment subscriptions based on the page they subscribed?

Yes! Please see our guide Auto-Segment By Subscription Page.

Why is my prompt not showing?

The Native Browser Prompt will not show while in Incognito Mode, Private Browser mode or Guest Browser mode. It will also not show right away on Safari 12.1+ or Firefox 72+ (more details).

Also make sure you are using a browser and device that supports web push.

Check your prompt setup to make sure Auto-prompt is turned on and the Delayed Prompts are not blocking you.

Apple released support for iOS Web Push notifications in 2023, and there are some additional requirements to prompt users for their subscription. More information can be seen in the Mobile Web Push for iOS/iPadOS guide.

Last would be to follow these steps to reset your cookie and browser cache to visit your site like a first-time user.

How can I show the prompt on only certain pages?

If you use Typical Setup, make sure to disable Auto-Prompt for both Slide and Native prompts. If you use the bell prompt, you will need to remove the OneSignal init call on pages you do not want the bell to show or switch to the Custom Code Setup.

You can now trigger the Native or Slide prompt with the SDK methods. See the prompt guide for details.

WordPress Users: There is currently no way to disable the OneSignal subscription prompts on certain pages/posts through the plugin directly. This will require adding code to the site.

We provide two options on how to setup the prompts on different pages of your site:
https://documentation.onesignal.com/docs/web-push-wordpress-faq#how-do-i-enable-the-plugin-for-certain-pages-only

Why do I see the Slide Prompt on Firefox when I want the Native Browser Prompt?

With Firefox 72+ there is a change that requires a user to click a button to show the native browser prompt. If you try to automatically show the native browser prompt, you will see an icon within the browser like this:

The user must click this icon to view the Native Browser Prompt on Firefox. This is why we default to the Slide Prompt on Firefox because it is more "eye-catching" and requires the 2-step opt-in in either case.

If you do not want to show the Slide Prompt as default, you must turn off the "Auto-Prompt" switch in the Prompt Editor:

Press "Save" and "Save" again on the next page. You can then use the OneSignal.Slidedown.promptPush(); or OneSignal.showNativePrompt() SDK method to trigger the Native Prompt on any page you want.

Why do I see the Slide Prompt on Mobile when I want the Native Browser Prompt?

The reason for this behavior is due to a change that Google made on December 5th 2017 to Chrome on Android. It is a very user-unfriendly pop-up that we deliberately added the double prompt on Android to preventt your users from having a bad experience on your site. 

For more details on this or if you really want to only show just the native prompt see Why is Slide Prompt Showing on Mobile.

Why does the welcome notification appear before the slide prompt is dismissed?

If you are seeing the welcome notification and the slide prompt, then you could be doing the following:

1. make sure you are not calling OneSignal.Slidedown.promptPush(); or OneSignal.showNativePrompt()
2. check that your init code does not have autoRegister: true set
3. check that you are not triggering the slide prompt with OneSignal.Slidedown.promptPushCategories(); or OneSignal.showSlidedownPrompt({force:true})
4. check that you are not calling the native browser API for trigging the "native prompt" which is the requestPermission method.