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

Slide Prompt

OneSignal Slide Prompt Details: Customizations, Triggering, and FAQ

The OneSignal Slide Prompt displays top-down center of the browser on desktop and bottom-up center on mobile. This is the most attention-grabbing prompt offered by OneSignal and is shown before the required Native Browser Prompt.

Generally, this prompt is used to gauge user interest and cannot replace the Native Browser Prompt.


  • Desktop (Firefox/Chrome) and Android Chrome versions of Slide Prompt

Add Slide Prompt Icon

You can customize the OneSignal Slide Prompt's icon and text. Currently you cannot customize the color, size, or font.

Set the icon in Settings > All Browsers configuration > Step 2 Default Icon URL. You can upload an image or paste a URL to the icon file.

Icon file must be .png or .jpg and at least 80x80 pixels (Recommended size is 192x192 pixels).

If you do not have a Default Notification Icon URL set, OneSignal will show a generic bell icon.


Typical Setup Slide Prompt

Text and delay customizations happen within Settings > All Browsers Configuration > Step 3 Permission Prompt Setup > Slide Prompt.

Customizable options for Slide Prompt.

OptionDetails
Customize slide prompt textAllows editing the message and button text. Not currently supported: Changing Font, Bold, Italicize, Color, adding links.
Auto-promptShow the prompt without additional code. Adds a delay on showing the prompt based on both time and/or number of page views.
Page ViewsAmount of times the user visits a URL of your site with the OneSignal code.
0 or 1 page view is the first time they visit the site.
SecondsAmount of time that needs to pass while the user is on the page of your site with the OneSignal code for the prompt to show.
0 seconds means show as soon as possible (after the site loads).
300 seconds means show after 5 minutes.
CategoriesTurns on Category Slidedown feature

You can combine Page Views and Seconds together. For example, if your common user visits your home page, another page and a 3rd page, you can set: 3 page views and 30 seconds. The prompt will show on the 3rd page and after 30 seconds has passed.

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 in the same place as the Slide Prompt. Simply click on the toggle for Categories to turn on this feature. It can also be configured via custom code OneSignal implementations.

Example

When a user opts into a category like "Sports", they will be automatically tagged (see Data Tags feature) with a 1 or a 0 value on the tag. A value of 1 indicates the user has opted in and a 0 indicates they don't want notifications of that category.

For example, based on the configuration above, a user may end up with the tags {world_news: 0, usa_news: 1, sports: 1, technology: 1} after clicking through the Category Slidedown depending on their personal interests. These tags can then be used in user segmentation.

Custom Code Setup for Category Slidedown

Triggering the Slide Prompt or Category Slidedown

To trigger these prompts programmatically, toggle off the Auto-prompt switch. Then use the following functions to show the prompts:

PromptFunction
Slide Prompt (reference)OneSignal.showSlidedownPrompt()
Category Slidedown (reference)OneSignal.showCategorySlidedown()

👍

Save Settings!

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


WordPress Slide Prompt

The OneSignal WordPress Plugin handles text customizations through the plugin. For updating the icon, see above Add Slide Prompt Icon.

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

Automatically prompt new site visitors with OneSignal Slide Prompt before Native Browser Prompt (recommended)

Don't forget to press "Save" at the bottom of the plugin.

To customize the Slide prompt text, in the plugin go to "Prompt Customization".

Select "Customize the Prompt text" and add your Action Message, Accept Button Text and Cancel Button Text, 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 Setup Slide Prompt

The Custom Code Setup is for integrating OneSignal with your own custom Javascript. It is recommended to use the Typical Setup.

You may customize the text in the Slide Prompt by including the contents in your initialization function:

// Your other init options here
promptOptions: {
    slidedown: {
      enabled: true,
      autoPrompt: true,
      timeDelay: 20,
      pageViews: 3,
      /* These prompt options values configure both the HTTP prompt and the HTTP popup. */
    /* actionMessage limited to 90 characters */
    actionMessage: "We'd like to show you notifications for the latest news and updates.",
    /* acceptButtonText limited to 15 characters */
    acceptButtonText: "ALLOW",
    /* cancelButtonText limited to 15 characters */
    cancelButtonText: "NO THANKS",
    }
}
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  window.OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "YOUR_APP_ID",
      safari_web_id: 'YOUR_SAFARI_ID',
      notifyButton: {
        enable: true,
      },
      promptOptions: {
        slidedown: {
          enabled: true,
          autoPrompt: true,
          timeDelay: 20,
          pageViews: 3,
          actionMessage: "We'd like to show you notifications for the latest news and updates.",
        acceptButtonText: "ALLOW",
        cancelButtonText: "NO THANKS",
        }
      }
    });
  });
</script>
<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",
      subdomainName: "your_label", /* The label for your site that you added in Site Setup mylabel.os.tc */
      promptOptions: {
        /* These prompt options values configure both the HTTP prompt and the HTTP popup. */
        /* actionMessage limited to 90 characters */
        actionMessage: "We'd like to show you notifications for the latest news and updates.",
        /* acceptButtonText limited to 15 characters */
        acceptButtonText: "ALLOW",
        /* cancelButtonText limited to 15 characters */
        cancelButtonText: "NO THANKS"
      }
    });
    OneSignal.showSlidedownPrompt();
  });
</script>

Category Slidedown with Custom Code

You can activate the Category Slidedown via custom code by passing in an extra parameter categories to the slidedown parameter:

categories parametertypedescription
updateMessagestringOptional
This is the message shown whenever the Category Slidedown is re-shown (the user is already subscribed).

Limit: 90 chars

Default: "Update your push notification subscription preferences."
positiveUpdateButtonstringOptional
This is the text that will be displayed on the positive button whenever the Category Slidedown is re-shown (the user is already subscribed).

Limit: 16 chars

Default: "Save Preferences"
negativeUpdateButtonstringOptional
This is the text that will be displayed on the negative button whenever the Category Slidedown is re-shown (the user is already subscribed).

Limit: 16 chars

Default: "Cancel"
tagsArray of ObjectsRequired
These are the categories that will be displayed in the slidedown.

The tag in this case is the Tag key and the label is what the end-user will see.
promptOptions: {
    // other prompt options (see above)
  
    slidedown: {
      autoPrompt: true,
      enabled: true,
      categories: {
        updateMessage: "Would you like to update your notification preferences?",
        positiveUpdateButton: "Howdy, yes",
        negativeUpdateButton: "Cancel",
        tags: [
          {
            tag: "politics",
            label: "Politics",
          },
          {
            tag: "usa_news",
            label: "USA News",
          },
          {
            tag: "world_news",
            label: "World News",
          },
          {
            tag: "culture",
            label: "Culture",
          }
        ]
      }
    }
}
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  window.OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "YOUR_APP_ID",
      safari_web_id: 'YOUR_SAFARI_ID',
      notifyButton: {
        enable: true,
      },
      promptOptions: {
        actionMessage: "We'd like to show you notifications for the latest news and updates.",
        acceptButtonText: "ALLOW",
        cancelButtonText: "NO THANKS",
        slidedown: {
          enabled: true,
          autoPrompt: true,
          timeDelay: 20,
          pageViews: 3,
          categories: {
            updateMessage: "Would you like to update your notification preferences?",
            positiveUpdateButton: "Howdy, yes",
            negativeUpdateButton: "Cancel",
            tags: [
              {
              tag: "politics",
              label: "Politics",
              },
              {
              tag: "usa_news",
              label: "USA News",
              },
              {
              tag: "world_news",
              label: "World News",
              },
              {
              tag: "culture",
              label: "Culture",
              }
            ]
          }
        }
      }
    });
  });
</script>

You can trigger the Slide Prompt anytime via the the showSlidedownPrompt method.

You can trigger the Category Slidedown anytime via the the showCategorySlidedown method.

📘

RECOMMENDED:

See examples for Adding a Prompt Delay.


Slide Prompt FAQ

How many times does the slide prompt show?

Please follow this link for more details.

How do I show the prompt in different languages?

This will require the Custom Code Setup. When you detect the browser language with your own setup code, you can initialize OneSignal with the language you want to show.

Why isn't my Slide Prompt showing up?

Even if you trigger showSlidedownPrompt(), it may not always show the message. The message will not be shown if any of the following are true:

  • The user previously dismissed the message by clicking the "No Thanks" button
  • HTTP sites: The user has blocked notifications for your-label.os.tc
  • The user is already successfully subscribed to notifications
  • You have manually opted out the user via our setSubscription(false) method
    • If you've intentionally disabled a user's permissions by calling setSubscription(false), you must manually opt the user back in by calling setSubscription(true) our drop-down prompt will not show.

If the prompt is not shown, the showSlidedownPrompt() method returns a Promise that resolves to a string value briefly describing the reason the prompt was not shown. You may also enable debug logging for the SDK via OneSignal.log.setLevel('trace'); to see explanations of why the prompt is not shown.

Updated 11 days ago



Slide Prompt


OneSignal Slide Prompt Details: Customizations, Triggering, and FAQ

Suggested Edits are limited on API Reference Pages

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