OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Prompting

Prompts & Permission Requests to Subscribe Users to Push Notifications

Example showing and resetting the Slide Prompt with Category Tags.

"Prompting" is asking user's 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.

Prompting users effectively is the first step to gaining more subscribers.

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 Prompting Overview

Each browser provides its 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 are encouraged.

Quick Reference

Details

Delaying Prompts

Control when to show the prompts with time and/or page view delays or with code.

Slide Prompt

Setup the Slidedown Prompt and Category Tags which allow users to opt-in to the types of messages they want.

Bell Prompt

The famous OneSignal bell prompt that hangs out in the bottom corner of the site.

Custom Link prompt

Setup your own custom link or button that triggers that can trigger the native prompt or unsubscribe users via a click.

Native Browser Prompt

Details on how the required browser prompt operates and how to use it.

HTTP PopUp Prompt

If your site is HTTP, then you will want to configure this prompt.

FAQ

Prompting FAQs like translating, AB testing, re-showing, best practices below. Also see our General Web Push FAQ for answers to common questions.


OneSignal Prompts

OneSignal provides "soft prompts" that are shown before the Native Permission Prompt and engage the user to take action. They 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 push notifications and are highly recommended by the browsers. Permission prompts do three things:

  1. Inform a user of the value of subscribing to push notifications.
  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.

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.

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.

Learn more about Category Slidedown

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.

HTTP Pop-Up Prompt

HTTP only - The HTTP Pop-Up Prompt is presented in a separate pop-up window for HTTP sites. It cannot be triggered alone and must follow the above prompts.


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.


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

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.

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 Prompts after 2 page visits and 20 seconds have passed.
  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 users based on the page they subscribed?

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

Why is my prompt not showing?

Apple still does not support Web Push on iOS like iPhone and iPad. This is an Apple limitation and no push provider can provide Web Push Notifications on iPhone and iPad. You need an iOS mobile app to send push on iPhone and iPad. GoNative.io is a great way to turn your website into a mobile app.

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.

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 not a 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 2 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.showNativePrompt() SDK method to trigger the Native Prompt on any page you want. Example code:

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  var OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "3beb3078-e0f1-4629-af17-fde833b9f716",
    });
    OneSignal.showNativePrompt();
  });
</script>

Updated about a month ago



Prompting


Prompts & Permission Requests to Subscribe Users to Push Notifications

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.