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 class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>

QuerySelector - call actions based on when a user has clicked or engaged with your in-app

<button class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
<script>
document.querySelector(".tag-user").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">
<body>
<button class="push-prompt" data-onesignal-unique-label="my-push-prompt-button">Prompt Push</button>
<script>
      document.querySelector(".push-prompt").addEventListener("click", function(e) {
        OneSignalIamApi.triggerPushPrompt(e);
});
</script>
</body>

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">
<body>
<button class="location-prompt" data-onesignal-unique-label="my-location-prompt-button">Prompt Location</button>
<script>
  document.querySelector(".location-prompt").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);	
});
</script>
</body>

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">
<body>
      <div class="close-button" 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 class="close-button" data-onesignal-unique-label="my-close-button">Tag User</button>
<script>
    document.querySelector(".close-button").addEventListener("click", function(e) {
        OneSignalIamApi.close(e);
});
</script>
</body>

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">
<body>
<button class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
<script>
   document.querySelector(".tag-user").addEventListener("click", function(e) {
        OneSignalIamApi.tagUser(e, { fiz: "baz" });
});
</script>
</body>

Open URL

Open a URL in the device's mobile browser.

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">
<body>
<button class="open-url" data-onesignal-unique-label="my-open-url-button">Open URL</button>
<script>
   document.querySelector(".open-url").addEventListener("click", function(e) {
        OneSignalIamApi.openUrl(e, "https://foo.com");
});
</script>
</body>

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">
<body>
          <button class="add-click-name" data-onesignal-unique-label="my-add-click-name-button">Add Click Name</button>
<script>
      document.querySelector(".add-click-name").addEventListener("click", function(e) {
        OneSignalIamApi.addClickName(e, "test_click_name");
});
</script>
</body>

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">
<body>
          <button class="add-track-click" data-onesignal-unique-label="my-track-click-button">Track Click</button>
<script>
      document.querySelector(".add-track-click").addEventListener("click", function(e) {
        OneSignalIamApi.trackClick(e);
});
</script>
</body>

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">
<body>
<button class="send-outcome" data-onesignal-unique-label="my-send-outcome-button">Send Outcome</button>
<script>
      document.querySelector(".send-outcome").addEventListener("click", function(e) {
        OneSignalIamApi.sendOutcome(e, "test_outcome");
});
</script>
</body>

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;
        /* Tip: Make your close-button relatively large so it's easy to click */
        min-width: 48px;
        min-height: 48px;
      }

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

      .center-modal h1 {
        margin: 0px;
        margin-bottom: 12px;
        color: #222;
        font-size: 24;
        font-style: normal;
        font-weight: normal;
        text-align: center;
        text-decoration: none;
      }

      .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;
          grid-gap: 12px;
          width: 100%;
        }

        .button-column {
          width: 50%;
        }

        .center-modal {
          height: 80%;
        }
      }
    </style>
  </head>

  <body>
    <div class="center-modal">
      <div class="close-button" 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>
      <h1>Heading</h1>
      <img src="https://media.onesignal.com/iam/default_image_20200320.png" />
      <div class="button-container">
        <div class="button-column">
          <button class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
          <button class="push-prompt" data-onesignal-unique-label="my-push-prompt-button">Prompt Push</button>
          <button class="location-prompt" data-onesignal-unique-label="my-location-prompt-button">Prompt Location</button>
        </div>
        <div class="button-column">
          <button class="add-click-name" data-onesignal-unique-label="my-add-click-name-buton">Add Click Name</button>
          <button class="send-outcome" data-onesignal-unique-label="my-send-outcome-button">Send Outcome</button>
        </div>
      </div>
    </div>
    <script>
         // Your code here
      document.querySelector(".close-button").addEventListener("click", function(e) {
        OneSignalIamApi.close(e);
      });
      document.querySelector(".tag-user").addEventListener("click", function(e) {
        OneSignalIamApi.tagUser(e, { fiz: "baz" });
      });
      document.querySelector(".push-prompt").addEventListener("click", function(e) {
        OneSignalIamApi.triggerPushPrompt(e);
      });
      document.querySelector(".location-prompt").addEventListener("click", function(e) {
        OneSignalIamApi.triggerLocationPrompt(e);
      });
      document.querySelector(".add-click-name").addEventListener("click", function(e) {
        OneSignalIamApi.addClickName(e, "test_click_click_name_id");
      });
      document.querySelector(".send-outcome").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.