In-App Message API
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.addActionId(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 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>
- elements with an
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.
Updated about 1 month ago