Setup

These methods serve as a reference and are just a single step in the setup process. Make sure to follow the steps for your particular platform here:

• Web Push Set Up

Initializing the SDK

This should be called only once during application startup.

Call this from each page of your site to initialize OneSignal. This call is required before any other functions can be used.

OneSignal.init({
	appId: "YOUR ONESIGNAL APP ID"
});

// init(config: AppUserConfig): Promise<void>
OneSignal.init({
	appId: "YOUR ONESIGNAL APP ID"
});

Init options are as follows. These only work with Custom Code Setup:

Init promptOptions parameters

Pass in these optional parameters within promptOptions when initializing to localize the prompts to your custom text and language. All entries are limited in length. Foreign characters accepted. Each parameter is optional, and its default is used when it is not included.

Init welcomeNotification parameters

Pass in these optional parameters within welcomeNotification when initializing to customize or disable the welcome notification sent to new site visitors. Any person visiting your site for their first time, or an existing user who has completely cleared their cache is considered a new site visitor.

Init notifyButton parameters

Pass in these optional parameters within notifyButton when initializing to enable and customize the Subscription Bell (formerly known as the notify button). All parameters below are optional. If not set, they will be replaced with their defaults.

The following is a basic template of how you would call init().

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(function(OneSignal) {
  OneSignal.init({
    appId: "99397374-10fe-4865-b62d-d8b71114b320",
    safari_web_id: "web.onesignal.auto.20f3ee95-6f21-4aad-a9bb-9c5899a4353a",
    notifyButton: {
      enable: true,
    },
    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: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>

User

OneSignal creates and stores subscription-level data under a unique ID called onesignal_id. Users can have multiple subscription records based on how many channels they subscribe to with your OneSignal app.

Logging in a user

Login to OneSignal under the user identified by the externalId provided. Logging a user into the OneSignal SDK will switch the context to that specific user.

• If the externalId exists, the user will be retrieved, and the context will be set from that user information. If operations have already been performed under a device-scoped user, they will not be applied to the now logged-in user, and their information will be lost.
• If the [externalId] does not exist, the user will be created, and the context will be set from the current local state. If operations have already been performed under a device-scoped user, those operations will be applied to the newly created user.

OneSignal.login("EID");

Logging out a user

Log out the user previously logged in via login. The user property now references a new device-scoped user. A device-scoped user has no user identity that can later be retrieved, except through this device, as long as the app remains installed and the app data is not cleared.

OneSignal.logout();

Adding an alias

Set an alias for the current user. If the alias label exists on this user, it will be overwritten.

OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

Adding multiple aliases

Set aliases for the current user. If any alias labels exist on the user, they will be overwritten.

const aliases = {
 ALIAS_LABEL_01: "ALIAS_ID_01",
 ALIAS_LABEL_02: "ALIAS_ID_02",
 ALIAS_LABEL_03: "ALIAS_ID_03", 
};
OneSignal.User.addAliases(["ALIAS_LABEL_01": "ALIAS_ID_01", "ALIAS_LABEL_02": "ALIAS_ID_02"]);

Removing an alias

Remove an alias from the current user.

OneSignal.User.removeAlias("ALIAS_LABEL");

Removing multiple aliases

Remove aliases from the current user.

const aliases = ["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"];
OneSignal.User.removeAliases(aliases);

Data Tags

Data Tags are custom key : value pairs of string or number data you set on users based on events or user data of your choosing. See Data Tags Overview for more details on what tags are used for.

See Data Tag Implementation for SDK Method details.

Privacy

Opting into data privacy protections

Determines whether users must consent to privacy before sending their data to OneSignal. This should be set to true to ensure compliance before invoking the init method.

OneSignal.setConsentRequired(true);

Providing user consent

Sets whether privacy consent has been granted.

If your website is set to require the user's privacy consent or some action before they can subscribe to push, add requiresUserPrivacyConsent: true property in the OneSignal init call. This will stop our SDK from initializing until you call provideUserConsent(true).

You can also revoke consent by setting provideUserConsent(false). This will prevent further collection of user data. To delete the user's current data see Delete User Data.

OneSignal.setConsentGiven(true);

Push Notifications

Setting a default launch URL

Sets the default URL for notifications.

If you haven't set a default URL, your notification will open to the root of your site by default.

OneSignal.Notifications.setDefaultUrl("https://onesignal.com");

To set the default URL for notifications, provide a valid URL that you want to be launched when the notification is clicked. This default URL will be used if no other URL is specified when creating a notification. If you do specify a URL when creating a notification, the default URL will be overridden.

In the case of Safari, the default notification icon URL will be set to the Site URL that you have specified in your Safari settings, as this function is not available.

Setting a default title

Sets the default title to display on notifications.

OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");

If a notification is created with a title, the specified title always overrides this default title.

A notification's title defaults to the title of the page the user last visited. If your page titles vary between pages, this inconsistency can be undesirable. Call this to standardize page titles across notifications, as long as a notification title isn't specified.

Checking for push support

Returns true if the current browser supports web push.

const isSupported = OneSignal.Notifications.isPushSupported();

Getting notification permission status

Determine whether your site has notification permission.

This returns true when your site has permission to display notifications.

• This is just the sites's permission, does not factor in OneSignal's optOut status or the existence of the Subscription ID and Push Token, see OneSignal.User.PushSubscription for these.

let permission = await OneSignal.Notifications.permission; // boolean

If you're deleting your user entry on our online dashboard for testing, the SDK will not sync with our dashboard and so this method will still return true (because the browser itself remembers the site's permissions). Follow Clearing your cache and resetting push permissions to reset this in the browser itself.

Requesting notification permission

Requests push notifications permission via the native browser prompt.

Web SDK v15 see showNativePrompt method.

OneSignal.Notifications.requestPermission();

Listening to events on the notification

You can hook into the notification life-cycle by attaching your event handlers to a notification event. Calling addEventListener lets you add an arbitrary number of event handlers for notification events.

function eventListener(event) {
  console.log(`${event}`);
}

OneSignal.Notifications.addEventListener("eventname", eventListener);

Notification Events

Removing event handlers

Removes the event handler for the given event.

function eventListener(event) { // ... }

OneSignal.Notifications.removeEventListener("eventname", eventListener)

Notification clicked

This event will fire when the notification's body/title or action buttons are clicked.

function clickEventListener(event) {
  console.log(`click event: ${event}`);
}

OneSignal.Notifications.addEventListener("click", clickEventListener);

Notification will display

This event is called prior to a notification being displayed. This event is fired on your page. If multiple browser tabs are open to your site, this event will be fired on all pages on which OneSignal is active.

function foregroundWillDisplayListener(event) {
  console.log(`notification will display: ${notification}`);
}

OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);

Notification dismissed

This event occurs when:

• A user purposely dismisses the notification without clicking the notification body or action buttons
• On Chrome on Android, a user dismisses all web push notifications (this event will be fired for each web push notification we show)
• A notification expires on its own and disappears

Note: This event does not occur if a user clicks on the notification body or one of the action buttons. That is considered a notification click (see the Click event above).

This event is fired on your page. If multiple browser tabs are open to your site, this event will be fired on all pages on which OneSignal is active.

function notificationDismissedListener(event) {
  console.log(`dismiss event: ${event}`);
}

OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);

Notification permission changed

Event occurs when the user clicks Allow or Block or dismisses the browser's native permission request.

function permissionChangeListener(permission) {
  if (permission) {
    console.log(`permission accepted!`);
  }
}

OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);

Notification permission prompt displayed

Event occurs when the browser's native permission request has just been shown.

function promptListener() {
  console.log(`permission prompt dispslayed event: ${event}`);
}

OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);

Slidedowns

Display the OneSignal Slide Prompt on your sites. This type of prompt slides down from the top of the browser viewport on Desktop and up from the bottom on mobile devices. For more details, please refer to Prompting behavior if declined.

📘

Does not replace native browser prompt

This does not replace the Native Browser Prompt required for subscription. You must obtain permissions using the native browser prompt.

Prompting behavior

When declined, future calls will be ignored for at least three days. Further declines will lengthen the time required to elapse before prompting the user again – refer to our guide for more info on dismissing web promps.

To override this back-off behavior to prompt the user again, you can pass {force: true}. However, to provide a good user experience, bind the action to a UI-initiated event like a button click.

Prompting for notification permission

Displays the notification permission prompt.

OneSignal.Slidedown.promptPush();

promptPushCategories

Displays the notification permission prompt for notification categories.

OneSignal.Slidedown.promptPushCategories();

Prompting users to subscribe to SMS messages

Displays the SMS subscription prompt.

OneSignal.Slidedown.promptSms();

Prompting users to subscribe to email

Displays the email subscription prompt.

OneSignal.Slidedown.promptEmail();

Prompting users to subscribe to email and SMS simultaneously

Displays the SMS and email subscription prompts.

OneSignal.Slidedown.promptSmsAndEmail();

Listening to events on the Slidedown prompt

Adds an event listener for the slidedownShown event. The listener function takes a boolean parameter.

function slidedownEventListener(wasShown) {
	console.log(`Slidedown shown event ${wasShown}`);
}

OneSignal.Slidedown.addEventListener("slidedownShown", slidedownEventListener);

Removing event handlers

Removes an event listener for the slidedownShown event.

function slidedownEventListener(didShow) { // ... }

OneSignal.Slidedown.removeEventListener(slidedownEventListener);

Push Subscription

Subscription ID

The user's push subscription ID. See Subscriptions for more details.

OneSignal.User.PushSubscription.id;

Push Token

The subscription's push token. Required to receive push notifications.

OneSignal.User.PushSubscription.token;

Disabling a push subscription

Changes the subscription status of an opted-in push subscription to opted-out. The push subscription cannot get push notifications anymore until optIn() is called or use Update subscription API with enabled: true.

This method does not remove or invalidate push tokens. It is designed for sites that wish to have more granular control of which users receive notifications, such as when implementing notification preference pages.

The user's push subscription can only be opted-out if OneSignal.Notifications.permission is true.

OneSignal.User.PushSubscription.optOut();

Enabling a push subscription

If you previously called the optOut() method, this changes the subscription status to opted-in. If the push token on the subscription is valid, the user should be able to get push notifications again.

This method does not trigger the website prompts and does not set or validate push tokens. It is designed for sites that wish to have more granular control of which users receive notifications, such as when implementing notification preference pages.

The user's push subscription can only be changed back to opted-in if both conditions are met:

1. OneSignal.Notifications.permission is true.
2. the optOut() method was previously used.

OneSignal.User.PushSubscription.optIn();

Checking push subscription status

Returns true or false based on the current push subscription status.

OneSignal.User.PushSubscription.optedIn;

Listening to changes on the push subscription

The change listener is fired when any of the fields on the subscription change. The event includes both the current and the previous state.

PushSubscriptionNamespaceProperties

function pushSubscriptionChangeListener(event) {
  if (event.current.token) {
    console.log(`The push subscription has received a token!`);
  }
}

OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);

Email

OneSignal's Mobile and Web SDKs provide methods for collecting emails, logging out of emails, and tracking email subscription changes.

See Email SDK Methods for more details.

SMS

OneSignal's Mobile and Web SDKs provide methods for collecting phone numbers, logging out phone numbers, and tracking SMS subscriptions.

See SMS SDK Methods for more details.

Debugging

Enable logging to help debug if you run into an issue setting up OneSignal. This selector is static, so you can call it before initializing OneSignal. For more info, see Debugging with Browser DevTools.

Setting the log level

Set the logging level to print to the DevTools console.

OneSignal.Debug.setLogLevel(“trace”);

Additional log levels

• 'trace'
• 'debug'
• 'info'
• 'warn'
• 'error'