Web prompting overview

"Prompting" in this context refers to 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 and receive push notifications.

Web Push works on Desktop, Android and iOS, but please note that web push for iOS requires some additional steps to configure. If you have a mobile app, see How to Prompt for Push Permissions with In-App Messages.

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 required native Permission Prompt. These prompts do not replace the native Permission Prompt and do not subscribe the user to web push notifications.

OneSignal "soft" prompts are highly recommended by the browsers because they help gauge the user's interest in getting messages which increases the likelihood they will stay subscribed. Permission prompts do three things:

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

Slide, category, & email/phone prompts

The Slide, Category, and Email/Phone Prompts display top and center of your site on desktop and bottom-center on Android. These are the most attention-grabbing prompt and is shown before the required native Permission Prompt. None of these prompts can replace the native Permission Prompt.

552 — Example showing the Slide Prompt with Category Tags.

Prompt icon

Navigate to Settings > Platforms > Web Settings.

The Category, Slide, and Email/Phone prompt icon uses the Default Icon URL field when setting up your site. You can upload an image or paste a URL to the icon file. It must be .png or .jpg and recommended size is 256x256 pixels for Safari's requirements. If you do not have a Default Notification Icon URL set, OneSignal will show a generic bell icon. This can always be changed later.

Auto prompt & display

It's best to delay the prompt from showing on screen to give your users time to enjoy the site before asking them to subscribe. This can improve engagement and user experience.

Prompts can be delayed based on:

page views: the number of times a page is viewed/loaded on the screen
seconds: the amount of time that needs to pass on each page before the prompt can show

Page views and seconds are combined together in an "AND" relationship only. For example, if you set 3 page views and 30 seconds. The prompt will show on the 3rd page load and after 30 seconds have passed. If the user doesn't interact with the prompt, it will show again on each page load after 30 seconds until interacted with. Then it follows the back off logic.

Slidedown back off logic

The Slide, Category, and Email/Phone Prompts each follow the same back off logic after a user dismisses a prompt for the first time. It will show again after 3 days, 7 days, then 30 days if the user clicks "Allow" or "Cancel" and is still not subscribed.

For example, if a user first clicks "Allow" on the Slide Prompt, but "x" on the native Permission Prompt, then the Slide Prompt will not show again for 3 days. After 3 days, it will show again and if the user clicks "Cancel" or "Allow" but still doesn't subscribe, it will not show again for 7 days. After 7 days, if the user does this again, it will show every 30 days.

If the user clears cookies or browser data, the cycle resets. See FAQ: Clearing Cookies for details.

📘
Programmatically Show a Prompt
Use our SDK Prompting Methods to show the prompt with code. This can be used to override the back off logic.
Make sure to disable the "Auto Prompt" option to call these methods (see below).

Typical Site Setup: Delayed Prompt Setup (click to expand)

Navigate to Settings > Platforms > Web Settings > Permission Prompt Setup and either Add Prompt or select the type of prompt from the list.

Enable the Auto Prompt settings to add your desired delays.

When finished, press Done and Save again on the next page to see this go into effect.

Custom Code Site Setup: Delayed Prompt Setup (click to expand)

Within your OneSignal init code's promptOptions object. Use the autoPrompt and delay properties to change they delay. See Web SDK Reference for more details.

OneSignalDeferred.push(function(OneSignal) {
  OneSignal.init({
    appId: "your-app-id",
    promptOptions:{
      slidedown: {
        prompts: [
          autoPrompt: true,//true means display the prompt based on the delay options.
          delay: {
            pageViews: 3,
            timeDelay: 30
          }
        ]
      }
    }
  });
});

Text

Each prompt's "action message" allows for 90 characters while the buttons are 15 characters. Customizations to the text color, size, font and links is currently not available.

Typical Site Setup: Text Setup (click to expand)

Navigate to Settings > Platforms > Web Settings > Permission Prompt Setup and either Add Prompt or select the type of prompt from the list.

Toggle on the option to customize the text.

When finished, press Done and Save again on the next page to see this go into effect.

Custom Code Site Setup: Text Setup (click to expand)

Within your OneSignal init code's promptOptions object. Use the text properties. See Web SDK Reference for more details.

OneSignalDeferred.push(function(OneSignal) {
  OneSignal.init({
    appId: "your-app-id",
    promptOptions:{
      slidedown: {
        prompts: [
          text: {
            actionMessage: "The callout asking the user to opt-in. Up to 90 characters.",
            acceptButton: "Triggers the opt-in. Up to 15 characters.",
            cancelButton: "Cancels opt-in. Up to 15 characters."
          }
        ]
      }
    }
  });
});

Email & phone number prompt

The Email & Phone Number prompt adds optional text fields for users to add their own email and/or phone number. To help collect accurate contact information, we provide automatic format validation for the input field types.

After a user submits their information, we will create new email and/or sms Subscriptions for the Users so you can start messaging them across all your channels.

Typical Site Setup: Email/Phone Number Prompt Setup (click to expand)

Navigate to Settings > Platforms > Web Settings > Permission Prompt Setup > Add Prompt > Email/Phone Prompt.

Next, configure which channels you would like to capture and customize the action text, labels, and auto prompt delays.

When finished, press Done and Save again on the next page to see this go into effect.

Custom Code Setup: Email/Phone Number Prompt Setup (click to expand)

Within your OneSignal init code's promptOptions object, add the type to be either email, sms, or smsAndEmail. See Web SDK Reference for more details.

OneSignal.init({
  // Your other init options here
  promptOptions: {
      slidedown: {
        prompts: [
          {
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
         // { type: "push",...},//example adding push
        ]
      }
  }
  // Continue other init options here
}

Note: if no other parameters are passed into the slidedown options object, the default values will be used.

Subscription bell prompt

The subscription bell prompt is a small widget that resides in the bottom corner of your site, which users can click to bring up the Native Browser Prompt if they have not subscribed yet. 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.

You can customize the OneSignal Bell Prompt's color, size, bottom position, text and more! Currently you cannot customize the icon or place the bell in the top corners.

Typical Site Setup: Subscription Bell Prompt (click to expand)

Navigate to Settings > Platforms > Web Settings > Permission Prompt Setup > Add Prompt > Subscription Bell Prompt.

There are many ways to customize the bell. Our recommendation would be to use the default settings and change the Color to fit your site's unique color scheme.

When finished, press Done and Save again on the next page to see this go into effect.

WordPress Setup: Subscription Bell Prompt (click to expand)

The OneSignal WordPress Plugin handles all available visual customizations through the plugin.

Under Prompt Settings & Subscription Bell turn on Enable the Subscription Bell to start toggling the customizations.

Custom Code Setup: Subscription Bell Prompt (click to expand)

Use the notifyButton parameter in your web SDK initialization options. You may toggle between different examples for Bell Prompt customizations.

Hiding: To hide the subscription bell after a user subscribes or only show it on certain pages, be sure to return the value false or a Promise that resolves to the value false in the displayPredicate function during initialization. This function is evaluated before the subscription bell is shown. You may return any other value to show the subscription bell.

// Your other init options here
notifyButton: {
    enable: true, /* Required to use the Subscription Bell */
    size: 'medium', /* One of 'small', 'medium', or 'large' */
    theme: 'default', /* One of 'default' (red-white) or 'inverse" (white-red) */
    position: 'bottom-right', /* Either 'bottom-left' or 'bottom-right' */
    offset: {
        bottom: '0px',
        left: '0px', /* Only applied if bottom-left */
        right: '0px' /* Only applied if bottom-right */
    },
    showCredit: false, /* Hide the OneSignal logo */
    text: {
        'tip.state.unsubscribed': 'Subscribe to notifications',
        'tip.state.subscribed': "You're subscribed to notifications",
        'tip.state.blocked': "You've blocked notifications",
        'message.prenotify': 'Click to subscribe to notifications',
        'message.action.subscribed': "Thanks for subscribing!",
        'message.action.resubscribed': "You're subscribed to notifications",
        'message.action.unsubscribed': "You won't receive notifications again",
        'dialog.main.title': 'Manage Site Notifications',
        'dialog.main.button.subscribe': 'SUBSCRIBE',
        'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',
        'dialog.blocked.title': 'Unblock Notifications',
        'dialog.blocked.message': "Follow these instructions to allow notifications:"
    }
}

// Your other init options here
notifyButton: {
  enable: true, // Required to use the Subscription Bell
  // Your other Subscription Bell settings here
  colors: { // Customize the colors of the main button and dialog popup button
    'circle.background': 'rgb(84,110,123)',
    'circle.foreground': 'white',
    'badge.background': 'rgb(84,110,123)',
    'badge.foreground': 'white',
    'badge.bordercolor': 'white',
    'pulse.color': 'white',
    'dialog.button.background.hovering': 'rgb(77, 101, 113)',
    'dialog.button.background.active': 'rgb(70, 92, 103)',
    'dialog.button.background': 'rgb(84,110,123)',
    'dialog.button.foreground': 'white'
  },
}

// Your other init options here
notifyButton: {
    /* Your other Subscription Bell settings here ... */
    enable: true,
    displayPredicate: function() {
      /* The user is subscribed, so we want to return "false" to hide the Subscription Bell */
      return !OneSignal.Notifications.permission
    },
}

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  var OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "YOUR_APP_ID",
      notifyButton: {
        enable: true, /* Required to use the Subscription Bell */
      /* SUBSCRIPTION BELL CUSTOMIZATIONS START HERE */
        size: 'medium', /* One of 'small', 'medium', or 'large' */
        theme: 'default', /* One of 'default' (red-white) or 'inverse" (white-red) */
        position: 'bottom-right', /* Either 'bottom-left' or 'bottom-right' */
        offset: {
            bottom: '0px',
            left: '0px', /* Only applied if bottom-left */
            right: '0px' /* Only applied if bottom-right */
        },
        showCredit: false, /* Hide the OneSignal logo */
        text: {
            'tip.state.unsubscribed': 'Subscribe to notifications',
            'tip.state.subscribed': "You're subscribed to notifications",
            'tip.state.blocked': "You've blocked notifications",
            'message.prenotify': 'Click to subscribe to notifications',
            'message.action.subscribed': "Thanks for subscribing!",
            'message.action.resubscribed': "You're subscribed to notifications",
            'message.action.unsubscribed': "You won't receive notifications again",
            'dialog.main.title': 'Manage Site Notifications',
            'dialog.main.button.subscribe': 'SUBSCRIBE',
            'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',
            'dialog.blocked.title': 'Unblock Notifications',
            'dialog.blocked.message': "Follow these instructions to allow notifications:"
        },
        colors: { // Customize the colors of the main button and dialog popup button
           'circle.background': 'rgb(84,110,123)',
           'circle.foreground': 'white',
           'badge.background': 'rgb(84,110,123)',
           'badge.foreground': 'white',
           'badge.bordercolor': 'white',
           'pulse.color': 'white',
           'dialog.button.background.hovering': 'rgb(77, 101, 113)',
           'dialog.button.background.active': 'rgb(70, 92, 103)',
           'dialog.button.background': 'rgb(84,110,123)',
           'dialog.button.foreground': 'white'
         },
        /* HIDE SUBSCRIPTION BELL WHEN USER SUBSCRIBED */
        displayPredicate: function() {
            return OneSignal.isPushNotificationsEnabled()
                .then(function(isPushEnabled) {
                    return !isPushEnabled;
                });
        }
      }
    });
  });
</script>

Custom link prompt

A code snippet you can add to your site's markup that will render a button or link that triggers the native Browser Prompt when clicked. Can be customized through the dashboard at any time without changes to your site's code.

A few examples of where it could be a good idea to have a prompt:

Adding a question right after an article: "Liked this article? Want to get more updates delivered to your desktop?"
In the footer of your site.
Having a sign up in a sticky pane at the top/bottom of your site.
And many more...

Typical Site Setup: Custom Link Prompt (click to expand)

Navigate to Settings > Platforms > Web Settings > Permission Prompt Setup > Add Prompt > Custom Link.

Update your settings and add the code to your site. You can always come back to this page to update the settings again later.

When finished, press Done and Save again on the next page to see this go into effect.

Custom Code Setup: Custom Link (click to expand)

Within your OneSignal init code's promptOptions object, add the customlink object and its available properties.

// Your other init options here
promptOptions: {
  customlink: {
    enabled: true, /* Required to use the Custom Link */
    style: "button", /* Has value of 'button' or 'link' */
    size: "medium", /* One of 'small', 'medium', or 'large' */
    color: {
      button: '#E12D30', /* Color of the button background if style = "button" */
      text: '#FFFFFF', /* Color of the prompt's text */
    },
    text: {
      subscribe: "Subscribe to push notifications", /* Prompt's text when not subscribed */
      unsubscribe: "Unsubscribe from push notifications", /* Prompt's text when subscribed */
      explanation: "Get updates from all sorts of things that matter to you", /* Optional text appearing before the prompt button */
    },
    unsubscribeEnabled: true, /* Controls whether the prompt is visible after subscription */
  }
}

Add the following markup on your page where you want the widget to render.

<div class='onesignal-customlink-container'></div>

Styling

To keep things simple and to get the flexibility of changing the appearance of the widget at any time through dashboard all you have to add to your markup is a div container with our special class name. If for some reason you find our styling to configurable enough there are a way to customize it further.

All elements have a special class onesignal-reset that removes any prior styling from the element to make sure there are no conflict with our internal styles and that it looks exactly as you've defined it in the dashboard.

If you ever find yourself in need to redefine any OneSignal styles, here is a short reference of the classes used in the Custom Link widget

Class Name	Applies to
onesignal-customlink-container	Main container
onesignal-customlink-subscribe	Action button
onesignal-customlink-explanation	Paragraph with a custom explanation text
state-subscribed	All components internal to the main container
state-unsubscribed	All components internal to the main container
button	Action button if in button mode
link	Action button if in link mode
small	All components internal to the main container
medium	All components internal to the main container
large	All components internal to the main container
hide	All components internal to the main container if unsubscribeEnabled is set to false

To override any of them you have to create a CSS rule with higher specificity, combining the class name with the parent element id should be enough. But beware of the conflicts, our internal styles may change.

Native permission prompt

Each browser has their own variation of a Permission Prompt that a user is required to select "Allow" to subscribe to push notifications for your site. This prompt cannot be edited and will show immediately after using any of the OneSignal soft prompts. If you decide to show this prompt without a OneSignal prompt, you can add Auto Prompt options like the OneSignal Slidedown prompts.

🚧
Browser Limitations
Chrome, Firefox and Safari have changed how prompting works. If you trigger the native Permission Prompt, you may see the following changes:
Chrome 80+ adds a quieter UI for prompting users who typically deny permissions and automatically for sites that get denied for push more frequently.
Safari 12.1+ and Firefox 72+ add the requirement for a "user gesture" (clicking a button) before the native prompt is shown.
Read more about these changes and best practices in our blog post: Browsers Are Changing How Notification Permission Prompts Work.
OneSignal already provides what you need to stay ahead of these changes with our OneSignal Prompts and the ability to show these prompts at relevant moments.

Native Permission Prompt Back Off Logic

The back off logic for the native Permission Prompt is controlled by the browser directly.

If a user clicks "Block" (Chrome), "Don't Allow" (Safari), or "Never Allow" (Firefox) then 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 then the following occurs:

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. 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.

Typical Site Setup: Native Prompt (click to expand)

Navigate to Settings > Platforms > Web > Permission Prompt Setup > Add Prompt > Push Prompt > Native Prompt.

When finished, press Done and Save again on the next page to see this go into effect

WordPress Setup: Native Prompt (click to expand)

To enable the Native Prompt upon visiting the site, go to "Prompt Settings & Subscription Bell" and enable:

Attempt to automatically prompt new site visitors with Native Browser Prompt (not recommended)

This is found under the "Subscription Bell" options and above the "Prompt Customizations" options. Then press "Save" at the bottom of the plugin.

If you would like to add a delay to this prompt, it will require adding some additional setup. Please see the WordPress Prompt Delay Code for more.

Custom Code: Native Prompt (click to expand)

Use the following methods when ready to prompt:

Web SDK v16+ OneSignal.Notifications.requestPermission(); method
Web SDK v15 OneSignal.showNativePrompt(); method

FAQ

Prompt customizations

How to translate/localize the prompt?

Currently you will need to select the Custom Code Setup. Then programmatically change the language of the prompts by detecting the user's browser language and initialize the OneSignal SDK with different text(s).

The native Permission Prompt will automatically translate to the browser's set language.

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.

Can I segment subscriptions based on the page they subscribed?

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

Can I change the bell icon?

You cannot change the bell image, but you can change the colors, text and put it on the bottom left of bottom right of the page.

Can I change the categories based on page?

Yes! This will require using the Custom Code Setup and adding the categories through code based on the above setup configurations.

How to track Slide Prompt Events?

The OneSignal Web SDK has the Slide Prompt Event Methods to detect when it shows on the screen, when it is closed, and the "Allow" or "Cancel" action.

Display & triggers

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

For OneSignal Prompts, see Slidedown Back Off Logic.

For the native Permission Prompts, see Native Permission Prompt Back Off Logic.

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 Web SDK.

Troubleshooting

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 Permission Prompt on Firefox. This is why we default to the Slide Prompt on Firefox because it 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 (don't forget to press the Save button), then use the Web SDK requestPermission() method.

Why do I see the Slide Prompt on mobile when I want the native Permission Prompt?

On December 5th 2017, Google changed how the native Permission Prompt looks on Chrome for Android. It is a very user-unfriendly pop-up that takes over the entire screen of your site. We deliberately added the double prompt on Android to prevent your users from having a bad experience on your site.

If you do not want to show the Slide Prompt, you must turn off the Auto Prompt switch in the Prompt Editor (don't forget to press the Save button), then use the Web SDK requestPermission() method.

Why does the slide prompt keep showing up?

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

Why is my prompt not showing?

A browser's native Permission Prompt may not show if one of these conditions is true:

The browser prevented the prompt from showing.
The user has already allowed notifications or already subscribed
The user blocked notifications. If a user clicks "Block" (Chrome), "Don't Allow" (Safari), or "Never Allow" (Firefox) they can never be prompted again and must subscribe through a multi-step process in the browser settings. This is why it is recommended to use the OneSignal Prompts.
Auto Prompt is turned off and no call to requestPermission();
The native Permission 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).
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 or you are using our Web SDK to prompt users.

For iOS, 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.

Web Permission Prompts

Web prompting overview

OneSignal prompts

Slide, category, & email/phone prompts

Prompt icon

Auto prompt & display

Slidedown back off logic

📘
Programmatically Show a Prompt

Text

Categories

1. Disable the plugin prompts

2. Switch to a manual initialization of OneSignal

3. Add custom JavaScript code to your site.

Code examples

Email & phone number prompt

Subscription bell prompt

Custom link prompt

Styling

Native permission prompt

🚧
Browser Limitations

Native Permission Prompt Back Off Logic

FAQ

Prompt customizations

Display & triggers

Troubleshooting

Web prompting overview

OneSignal prompts

Slide, category, & email/phone prompts

Prompt icon

Auto prompt & display

Slidedown back off logic

📘Programmatically Show a Prompt

Text

Categories

1. Disable the plugin prompts

2. Switch to a manual initialization of OneSignal

3. Add custom JavaScript code to your site.

Code examples

Email & phone number prompt

Subscription bell prompt

Custom link prompt

Styling

Native permission prompt

🚧Browser Limitations

Native Permission Prompt Back Off Logic

FAQ

Prompt customizations

Display & triggers

Troubleshooting

📘
Programmatically Show a Prompt

🚧
Browser Limitations