Web SDK reference

​

Setup & debugging

​

init()

window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});

​

promptOptions parameters

​

notifyButton parameters

​

welcomeNotification parameters

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    safari_web_id: "YOUR_SAFARI_WEB_ID",
    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>

​

setLogLevel()

  OneSignal.Debug.setLogLevel("trace");

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

​

User identity & properties

​

login(external_id)

• The SDK switches to that existing user.
  • You may see a 409 Conflict in the browser network log or console. It means the External ID already exists in the app; it is expected in this path and is not usually a promise rejection you must handle.
• The current onesignal_id is discarded and the existing onesignal_id for that user is loaded.
• The current device (web push Subscription) is linked to the existing user.
• Anonymous data collected before login is not merged and is discarded. This includes tags, session data, email/SMS Subscriptions, and other local user properties.

• A new user is created using the current onesignal_id.
• All data collected while the user was anonymous is retained.
• The device (web push Subscription) becomes linked to this new user.

• The SDK automatically retries the login request on network failures or server errors.
• You do not need to implement your own retry logic.

• Call login(external_id) every page load once you know the user’s ID (for example, after sign-in or session restore).
• Call it again whenever the signed-in user changes (account switch).
• Do not call login before you have a stable, known user identifier.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});

​

logout()

• Removes the external_id from the current web push Subscription. Does not remove the external_id from other Subscriptions.
• Resets the onesignal_id to a new anonymous user.
• Any new data (e.g tags, Subscriptions, session data, etc.) will now be set on the new anonymous user until they are identified with the login method.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});

​

OneSignal.User.onesignalId

• After the OneSignal SDK finishes initializing
• After a user is identified with login(external_id)
• After switching users or restoring a session

• Tracking anonymous users before an External ID is set
• Storing the OneSignal ID in your backend for support or debugging
• Correlating OneSignal users with internal logs
• Displaying the ID for troubleshooting or QA

const onesignalId = OneSignal.User.onesignalId;

​

OneSignal.User.externalId

  const externalId = OneSignal.User.externalId;

​

addEventListener() User State

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });

​

addAlias(), addAliases(), removeAlias(), removeAliases()

• Set external_id with login() before adding aliases. Aliases added to subscriptions without external_id will not sync across multiple subscriptions.
• See Aliases for details.

  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);

​

getLanguage(), setLanguage()

  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");

​

Custom events

• name - Required. The name of the event as a string.
• properties - Optional. Key-value pairs to add to the event. The properties dictionary or map must be serializable into a valid JSON Object. Supports nested values.

{ 
  "os_sdk": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}

​

trackEvent()

OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});

​

Tags

​

addTag(), addTags()

• Values will be replaced if the key already exists.
• Exceeding your plan’s tag limit will cause the operations to fail silently.

  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });

​

removeTag(), removeTags()

  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);

​

getTags()

  const tags = OneSignal.User.getTags()

​

Privacy

​

setConsentRequired()

  OneSignal.setConsentRequired(true);

​

setConsentGiven()

• If setConsentRequired() or requiresUserPrivacyConsent is set to true, our SDK will not be fully enabled until setConsentGiven is called with true.
• If setConsentGiven is set to true and a Subscription is created, then later it is set to false, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until setConsentGiven is set to true again.
• If you want to delete the User and/or Subscription data, use our Delete user or Delete subscription APIs.

  OneSignal.setConsentGiven(true);

​

Subscriptions

​

User.PushSubscription.id

  const subscription_id = OneSignal.User.PushSubscription.id;

​

User.PushSubscription.token

  OneSignal.User.PushSubscription.token;

​

addEventListener() Push Subscription Changes

• The device receives a new push token from Google (FCM) or Apple (APNs)
• OneSignal assigns a subscription ID
• The optedIn value changes (e.g. called optIn() or optOut())
• The user toggles push permission in browser or OS settings, then returns to your site

  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

​

optOut(), optIn(), optedIn

• optOut(): Sets the current push subscription status to unsubscribed (even if the user has a valid push token).
• optIn(): Does one of the following:
  1. If the Subscription has a valid push token, it sets the current push subscription status to subscribed.
  2. If the Subscription does not have a valid push token, it attempts to display the push permission prompt.
• optedIn: Returns true if the current push subscription status is subscribed, otherwise false. If the push token is valid but optOut() was called, this will return false.

  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;

​

addEmail(), removeEmail()

• The email address becomes an email Subscription for the current user.
• The email may be created or reassigned.
• The same email address cannot exist multiple times in the same OneSignal app. If you see duplicate email addresses, check your REST API requests and contact support if needed.

• The email Subscription is removed from the current user.
• The current External ID is removed from the email Subscription.
• A new OneSignal ID is assigned to the email Subscription.
• Other Subscriptions (push, SMS, other emails) remain unaffected.

• Call login() first, then call addEmail(). Otherwise, the email may be attached to an anonymous user.
• Use a stable, verified email address.
• Follow Email reputation best practices.

  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

​

addSms(), removeSms()

• The phone number becomes an SMS Subscription for the current user.
• The number may be created or reassigned.
• The same phone number cannot exist multiple times in the same OneSignal app. If you see duplicate phone numbers, check your REST API requests and contact support if needed.

• The SMS Subscription is removed from the current user.
• The current External ID is removed from the SMS Subscription.
• A new OneSignal ID is assigned to the SMS Subscription.
• Other Subscriptions (push, email, other SMS) remain unaffected.

• Call login() first, then call addSms(). Otherwise, the SMS Subscription may be attached to an anonymous user.
• Always validate and normalize phone numbers to E.164 format before sending.
• Follow SMS Registration Requirements.

  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

​

Slidedown prompts

• If dismissed, future calls will be ignored for at least three days. Further declines will lengthen the time required to elapse before prompting the user again.
• To override back-off behavior, pass {force: true} to the method. However, to provide a good user experience, bind the action to a UI-initiated event like a button click.

​

promptPush()

• If using categories, call promptPushCategories() instead.
• Subject to backoff logic set by OneSignal. See Web permission prompts for more details.

  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});

​

promptPushCategories()

• If not using categories, call promptPush() instead.
• Subject to backoff logic set by OneSignal. See Web permission prompts for more details.

  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});

​

promptSms()

• Subject to backoff logic set by OneSignal. See Web permission prompts for more details.

  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});

​

promptEmail()

• Subject to backoff logic set by OneSignal. See Web permission prompts for more details.

  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});

​

promptSmsAndEmail()

• Subject to backoff logic set by OneSignal. See Web permission prompts for more details.

  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});

​

addEventListener() Slidedown

  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });

​

Push notifications

​

requestPermission()

  OneSignal.Notifications.requestPermission();

​

isPushSupported()

  const isSupported = OneSignal.Notifications.isPushSupported();

​

OneSignal.Notifications.permission

• true: The user has granted permission to display notifications.
• false: The user has either denied or not yet granted permission to display notifications.

  let permission = OneSignal.Notifications.permission;

​

addEventListener() Notifications

  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);

​

permissionChange

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

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

​

permissionPromptDisplay

  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

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

​

click

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

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

​

foregroundWillDisplay

  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

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

​

dismiss

• 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

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

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

​

setDefaultUrl()

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

​

setDefaultTitle()

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

​

Outcomes

​

sendOutcome()

  OneSignal.Session.sendOutcome('outcome name', 19.84);

​

sendUniqueOutcome()

  OneSignal.Session.sendUniqueOutcome('outcome name');