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 Outcome

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="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

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