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.

This prompt is used to gauge user interest and add Data Tags. It cannot replace the Native Browser Prompt.


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

Quick Reference

Details

Slide Prompt Customizations

Details on how the Slide Prompt works including:

Typical Setup Slide Prompt

Only Typical Setup has the dashboard editor to setup the Slide Prompt and Category Slidedown prompt without additional code.

WordPress Setup Slide Prompt

Slide Prompt Customizations are handled within the OneSignal WordPress plugin. For customizations see WordPress Plugin Questions.

Custom Code Slide Prompt

Code examples for adding the Slide and Category prompts programmatically. Cannot be used with Typical Setup.

Slide Prompt FAQ

Answers to the most common questions about the Slide and Category Prompts.


Slide Prompt Customizations

Customization

Details

Icon

Yes

  • Recommended size 256 x 256 pixels

Text

Character Count:

  • Action Message: 90 characters
  • Buttons: 15 characters
    Text color, size, font and links currently not available.

Category Tags

Yes

  • 10 Max Categories/Tags
  • Can be displayed anytime

Time Delays

Yes

  • Total Page Views
  • Time on page
    Prompts can be triggered programmatically as well for more control.

Color, Size, Font, Add Links, Localization

Coming Soon

Add Slide Prompt Icon

Set the icon in your OneSignal Dashboard > Settings > All Browsers configuration > 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 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

Category Tags

The Category Slidedown works just like the regular Slide Prompt except it also allows subscribers to opt-in or out of notification categories set as Data Tags.

There is a maximum 10 categories/tags that can be set within the prompt. Users will be opted-in to all categories by default unless they uncheck the appropriate boxes. Unchecking certain boxes by default is not currently supported.

Upon subscription all checked categories will be set as tags on the device with the tag key provided and a value of 1 for checked and 0 for unchecked. See Segments for details on creating segments for these categories with the User Tag filter.

Category Slidedown configuration


Triggering the Prompt

The Slide and Category Prompts can be shown to users automatically with Time Delays.

You can also trigger these prompts programmatically if you want more control of when they are shown.

To trigger these prompts programmatically, toggle off the Auto-prompt switch in Typical Setup or remove the Time delay code from Custom Code Setup. Then use the following functions to show the prompts:

Prompt

Function

Show Slidedown Prompt method

OneSignal.showSlidedownPrompt()

Show Category Slidedown method

OneSignal.showCategorySlidedown()

How to show the category slidedown to users already subscribed?

The category slide prompt, will tag the user with a key you set and value of 1 or 0 depending on if they check the category or not.

If one of your tags are breaking_news for example, then if the user selects it, the tag will be breaking_news: 1. If they uncheck it, they will have breaking_news: 0.

In either case, if the user is subscribed and selects or does not select this category/tag, it will be active on the device.

Using this knowledge with the OneSignal getTags method, we can detect if the device has any of these categories and present the prompt if not. Using the breaking_news tag for example:

var numVisitsTrigger = 3;//how many page visits till show prompt again

if (typeof localStorage !== "undefined") {
    var visitNumber = parseInt(localStorage.getItem("visitNumber"), 10);
    if (!isNaN(visitNumber)) {
        visitNumber += 1;
    } else {
        visitNumber = 0;
    }
    localStorage.setItem("visitNumber", visitNumber)

    if ((numVisitsTrigger % visitNumber) === 0) {
        console.log("visitNumber is a multiple of number of visits")
        OneSignal.push(function() {
            OneSignal.getTags(function(tags) {
                console.log(tags.breaking_news)
                if (!tags.breaking_news) {
                    OneSignal.showCategorySlidedown();
                }
            })
        });
    }
}

Using the Tags set from the Prompt

The category slide prompt, will tag the user with a key you set and value of 1 or 0 depending on if they check the category or not.

Within Segments you can create a segment using the User Tag filter is 1.

This will target all users interested in the category.


Typical Setup Slide Prompt

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

Customizable options for Slide Prompt.

Option

Details

Customize slide prompt text

Allows editing the message and button text. Not currently supported: Changing Font, Bold, Italicize, Color, adding links.

Auto-prompt

Show the prompt without additional code. Adds a delay on showing the prompt based on both time and/or number of page views.

Page Views

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

Seconds

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

Categories

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

Typical Setup Category Slidedown

You can add up to 10 Categories/tags and a unique message for triggering the Category Slidedown manually. See above Category Tags for more details on how Category Tags work.

To trigger the slide or category prompt, see above on Triggering the Prompt.

πŸ‘

Save Settings!

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

You may need to wait a minute and clear page cookies to see changes 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.

Slide Prompt Options:

// 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 parameter

type

description

updateMessage

string

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

positiveUpdateButton

string

Optional
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: 15 chars

Default: "Save Preferences"

negativeUpdateButton

string

Optional
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: 15 chars

Default: "Cancel"

tags

Array of Objects

Required
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>
// FIRST STEP: change to manual initialization in the Wordpress Plugin 
// (see https://bit.ly/2E2u5gk)
window.addEventListener('load', function() {
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      autoPrompt: true,
      enabled: true,
      timeDelay: 20,
      pageViews: 3,
      actionMessage: "Howdy, we would like to send you notifications",   
      acceptButtonText: "Accept",
      cancelButtonText: "Cancel",
      categories: {
        updateMessage: "Howdy, would you like to update your notification preferences?",
        positiveUpdateButton: "Update",
        negativeUpdateButton: "Cancel",
        tags: [
          {
            tag: "politics",
            label: "Politics",
          },
          {
            tag: "usa_news",
            label: "USA News",
          },
          {
            tag: "world_news",
            label: "World News",
          },
          {
            tag: "culture",
            label: "Culture",
          }
        ]
      }  
    }
  };

window.OneSignal = window.OneSignal || [];
/* Why use .push? See: http://stackoverflow.com/a/38466780/555547 */
window.OneSignal.push(function() {
  /* Never call init() more than once. An error will occur. */
  window.OneSignal.init(window._oneSignalInitOptions);
});
})

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.

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.

Updated about a month 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.