Our In-App JS Library allows you to leverage key functionalities whilst creating your In-App with our HTML Editor., such as tracking user actions, or prompting them for permissions. In summary, you can do:

Track Actions
Prompt for location and prompt for permissions for push
Tag Users
Send Outcomes
Close the In-App

The Basics

In order to work with our In-App JS Library you need to specify the following:

data-onesignal-unique-label - add this to the elements you are wanting to track, with a unique label. 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

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

Available Functions

Feature	Description	Example Function	Read More
Location Permission Prompt	Ask your user for their permission to obtain their current location. Also tracks the click.	`OneSignalIamApi.triggerLocationPrompt(e);`	Read More about Prompting for Location
Push Permission Prompt	Encourage your users to signup for push notifications. Also tracks the click	`OneSignalIamApi.triggerPushPrompt(e);`	Read More about Push Opt-in Prompt
Sending Outcomes	Track events or actions resulting from your in-apps. Also tracks the click	`OneSignalIamApi.sendOutcome(e, "test_outcome");`	Read More about Outcomes
Tagging Users	Tag users based on user input information, or a user action, for future segment. Examples can include. newsletter preferences, profile information and much more. Also tracks your users click.	`OneSignalIamApi.tagUser(e, { fiz: "baz" });`	Read More about Data Tags
Close In-App	Ensure your users have a way to close the in-app. Also tracks your users click.	`OneSignalIamApi.close(e);`
Add Click Name	Specify a Click Name to enable deep linking or other custom tracking. Tracks your users click	`OneSignalIamApi.addClickName(e, "test_click _name_id");`	Read More about How to deep link within the app
Track Click	Track the click and does nothing else	`OneSignalIamApi.trackClick(e);`
Open URL	Open a URL in the device's mobile browser.	`OneSignalIamApi.openUrl(e, "https://foo.com");`

Example Usage

Location Permission Prompt

<!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(".push-prompt").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
});
</script>
</body>

Push Permission Prompt

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

Close Button

<!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>
<script>
    document.querySelector(".close-button").addEventListener(“click”, function(e) {
        OneSignalIamApi.close(e);
});
</script>
</body>

Send Outcome

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

Tag User

<!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">Tag User</button>
<script>
   document.querySelector(".tag-user").addEventListener(“click”, function(e) {
        OneSignalIamApi.tagUser(e, { fiz: “baz” });
});
</script>
</body>

Click Name

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

<!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.addClickName(e);
});
</script>
</body>

Main 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 user'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.