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
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 >
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 >
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 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 >
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 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 >
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 ) + 20 px );
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 : 18 px ;
padding : 24 px ;
border-radius : 8 px ;
display : flex ;
flex-direction : column ;
justify-content : center ;
align-items : center ;
height : 85 % ;
width : 100 % ;
box-shadow : rgb ( 0 0 0 / 30 % ) 0 px 0 px 12.5 px , rgb ( 0 0 0 / 15 % ) 0 px 0 px 2.5 px ;
}
.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 : 48 px ;
min-height : 48 px ;
}
.center-modal img {
width : 100 % ;
min-height : 10 px ;
margin-bottom : 12 px ;
height : 100 % ;
object-fit : contain ;
}
.center-modal h1 {
margin : 0 0 12 px 0 ;
color : #222 ;
font-size : 24 px ;
text-align : center ;
}
.center-modal button {
font-size : 16 px ;
color : #fff ;
background-color : #1F8FEB ;
width : 100 % ;
padding : 12 px ;
border-radius : 4 px ;
border : none ;
margin-bottom : 12 px ;
}
.button-container {
display : flex ;
flex-direction : column ;
}
@media screen and ( min-width : 480 px ) {
.button-container {
flex-direction : row ;
gap : 12 px ;
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.