In-app message JavaScript APIs

This guide is for our in-app message JavaScript library used when creating in-app messages with our HTML Editor. If you are looking for SDK methods for triggers, in-app click handler, lifecycle methods and others, please see our Mobile SDK reference.

Required

data-onesignal-unique-label – must be included on the elements that trigger actions, with a unique label, to be handled correctly, and be tracked as a click. For example:

<button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">Tag User</button>

getElementById – call actions based on when a user has clicked or engaged with your in-app message:

document.getElementById("tag-user-button").addEventListener("click", function(e) { OneSignalIamApi.tagUser(e, { fiz: "baz" }); });

<button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
<script>
document.getElementById("tag-user-button").addEventListener("click", function(e) {
  OneSignalIamApi.tagUser(e, { fiz: "baz" });
});
</script>

Available functions

Push permission prompt

Displays the native permission prompt so your users can subscribe for push notifications.See Prompt for push permissions for more details.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="push-prompt-button" data-onesignal-unique-label="my-push-prompt-button">Prompt Push</button>
  <script>
    document.getElementById("push-prompt-button").addEventListener("click", function(e) {
      OneSignalIamApi.triggerPushPrompt(e);
    });
  </script>
</body>
</html>

Location permission prompt

Displays the native permission prompt so your users can opt-in to location tracking.See Location permission prompts for more details.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="location-prompt-button" data-onesignal-unique-label="my-location-prompt-button">Prompt Location</button>
  <script>
    document.getElementById("location-prompt-button").addEventListener("click", function(e) {
      OneSignalIamApi.triggerLocationPrompt(e);
    });
  </script>
</body>
</html>

Close in-app message

Dismiss the in-app message.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <div id="close-button-icon" data-onesignal-unique-label="close_button">
    <svg width="10" height="10" preserveAspectRatio="none" viewBox="0 0 8 8" fill="none"
      xmlns="http://www.w3.org/2000/svg">
      <path
        d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
        fill="#111111" />
    </svg>
  </div>

  <button id="close-button" data-onesignal-unique-label="my-close-button">Close</button>

  <script>
    document.getElementById("close-button").addEventListener("click", function(e) {
      OneSignalIamApi.close(e);
    });
  </script>
</body>
</html>

Tag user

Sets a Tag.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
  <script>
    document.getElementById("tag-user-button").addEventListener("click", function(e) {
      OneSignalIamApi.tagUser(e, { fiz: "baz" });
    });
  </script>
</body>
</html>

Open URL

Open a URL in the device’s mobile browser and automatically close the in-app message.May be used with Deep Linking depending on how the deep link was created.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="open-url-button" data-onesignal-unique-label="my-open-url-button">Open URL</button>
  <script>
    document.getElementById("open-url-button").addEventListener("click", function(e) {
      OneSignalIamApi.openUrl(e, "https://foo.com");
    });
  </script>
</body>
</html>

Click name

Specify an ID for the element being clicked which is then accessible via the in-app message click listener.May be used with Deep Linking depending on how the deep link was created.Click events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="add-click-name-button" data-onesignal-unique-label="my-add-click-name-button">Add Click Name</button>
  <script>
    document.getElementById("add-click-name-button").addEventListener("click", function(e) {
      OneSignalIamApi.addClickName(e, "test_click_name");
    });
  </script>
</body>
</html>

Track click

Track the click event if using an element without the other trackable methods.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="track-click-button" data-onesignal-unique-label="my-track-click-button">Track Click</button>
  <script>
    document.getElementById("track-click-button").addEventListener("click", function(e) {
      OneSignalIamApi.trackClick(e);
    });
  </script>
</body>
</html>

Send Outcome

Tracks a Custom OutcomeClick events are tracked automatically.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button id="send-outcome-button" data-onesignal-unique-label="my-send-outcome-button">Send Outcome</button>
  <script>
    document.getElementById("send-outcome-button").addEventListener("click", function(e) {
      OneSignalIamApi.sendOutcome(e, "test_outcome");
    });
  </script>
</body>
</html>

Example

Full HTML sample

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>OneSignal In-App Message</title>
  <style>
    body {
      margin: 0;
      padding-top: var(--safe-area-inset-top);
      padding-right: var(--safe-area-inset-right);
      padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
      padding-left: var(--safe-area-inset-left);
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
      display: flex;
      align-items: center;
    }

    .center-modal {
      position: relative;
      background: #FFF;
      margin: 18px;
      padding: 24px;
      border-radius: 8px;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      height: 85%;
      width: 100%;
      box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px, rgb(0 0 0 / 15%) 0px 0px 2.5px;
    }

    .center-modal .close-button {
      position: absolute;
      top: 0;
      right: 0;
      background: rgba(0, 0, 0, 0);
      border: none;
      z-index: 1;
      display: flex;
      justify-content: center;
      flex-direction: column;
      align-items: center;
      min-width: 48px;
      min-height: 48px;
    }

    .center-modal img {
      width: 100%;
      min-height: 10px;
      margin-bottom: 12px;
      height: 100%;
      object-fit: contain;
    }

    .center-modal h1 {
      margin: 0 0 12px 0;
      color: #222;
      font-size: 24px;
      text-align: center;
    }

    .center-modal button {
      font-size: 16px;
      color: #fff;
      background-color: #1F8FEB;
      width: 100%;
      padding: 12px;
      border-radius: 4px;
      border: none;
      margin-bottom: 12px;
    }

    .button-container {
      display: flex;
      flex-direction: column;
    }

    @media screen and (min-width: 480px) {
      .button-container {
        flex-direction: row;
        gap: 12px;
        width: 100%;
      }

      .button-column {
        width: 50%;
      }

      .center-modal {
        height: 80%;
      }
    }
  </style>
</head>
<body>
  <div class="center-modal">
    <button id="close-button" data-onesignal-unique-label="close-button" class="close-button">
      <svg width="10" height="10" preserveAspectRatio="none" viewBox="0 0 8 8" fill="none"
        xmlns="http://www.w3.org/2000/svg">
        <path
          d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
          fill="#111111" />
      </svg>
    </button>
    <h1>Heading</h1>
    <img src="https://media.onesignal.com/iam/default_image_20200320.png" alt="In-App Message" />
    <div class="button-container">
      <div class="button-column">
        <button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
        <button id="push-prompt-button" data-onesignal-unique-label="my-push-prompt-button">Prompt Push</button>
        <button id="location-prompt-button" data-onesignal-unique-label="my-location-prompt-button">Prompt Location</button>
      </div>
      <div class="button-column">
        <button id="add-click-name-button" data-onesignal-unique-label="my-add-click-name-button">Add Click Name</button>
        <button id="send-outcome-button" data-onesignal-unique-label="my-send-outcome-button">Send Outcome</button>
      </div>
    </div>
  </div>

  <script>
    document.getElementById("close-button").addEventListener("click", function(e) {
      OneSignalIamApi.close(e);
    });

    document.getElementById("tag-user-button").addEventListener("click", function(e) {
      OneSignalIamApi.tagUser(e, { fiz: "baz" });
    });

    document.getElementById("push-prompt-button").addEventListener("click", function(e) {
      OneSignalIamApi.triggerPushPrompt(e);
    });

    document.getElementById("location-prompt-button").addEventListener("click", function(e) {
      OneSignalIamApi.triggerLocationPrompt(e);
    });

    document.getElementById("add-click-name-button").addEventListener("click", function(e) {
      OneSignalIamApi.addClickName(e, "test_click_click_name_id");
    });

    document.getElementById("send-outcome-button").addEventListener("click", function(e) {
      OneSignalIamApi.sendOutcome(e, "test_outcome");
    });
  </script>
</body>
</html>

FAQ

Does Tag Substitution work for HTML IAMs?

Tag substitution will work for most HTML elements but will not work within script tags. Regular liquid syntax, like this will work: <div>Hi there {{ name | default: 'you' }}!</div> Here, the name OneSignal tag will be replaced with the device’s value for that tag, with ‘you’ being the default value if that tag isn’t set. Tag substitution will work for:

text displayed to the end user (text within a div, p, li, etc)
in <style> tags i.e. body { background-color: "{{ favorite_color | default: '#fff' }}"; }
HTML element attributes which take a url:
- elements with an href attribute
- elements with a src attribute
- action attribute on <form>
- data attribute on <object>

Tag substitution will NOT work within <script> tags Tag substitution does not work when using the “Send Test Message” button. You will need to test with a test user segment.

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

In-app message JavaScript APIs

Required

Available functions

Example

FAQ

Does Tag Substitution work for HTML IAMs?

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

​Required

​Available functions

​Example

​FAQ

​Does Tag Substitution work for HTML IAMs?

Required

Available functions

Example

FAQ

Does Tag Substitution work for HTML IAMs?