Create Custom HTML content for In-App Campaigns

To create a custom HTML in-app campaign, go to the Content tab of your campaign and from Type drop-down, select Custom HTML. This option give you full control over the visual design and content of your campaigns, compared to the other types: full-screen, banner, and modal. You can use HTML, CSS, and JavaScript to fully design and customise your in-app message content.

When you use a custom HTML in-app, the Xtremepush SDK continues to handle:

• Displaying and dismissing the message at the right time
• Positioning and animation
• Routing button actions (URLs, deeplinks, push permission requests) to the correct native behaviour
• Delivering analytics events

The HTML of your in-app message must handle:

• Layout, design, and responsiveness across screen sizes
• Wiring up any interactive elements (buttons, links) using the InAppMessage JavaScript methods
• Calling InAppMessage.init() after setting any configuration options

Build your message

For this in-app style, you'll need to write your own HTML code for both Portrait and Landscape orientations. By default, Portrait orientation is selected. You can use CSS and JavaScript as needed. There are a number of JavaScript methods available to manipulate the in-app message, details can be found in in-app message configuration and SDK methods.

🚧

HTML experts only

Using your own code may affect how the message is shown in different devices, preventing it from adjusting to the screen size (i.e., the "responsiveness" of the message). Make sure to use HTML that is responsive and review our in-app creative guidelines guide for best results.

In-app message configuration and SDK methods

Initialise the InAppMessage SDK

In order to be able to manipulate the in-app message you must add the following JavaScript line to import the InAPPMessage SDK in your custom HTML:

<script type = "text/javascript"
src = "https://api.xtremepush.com/sdk/inapp/v1/lib.js?v=1.0"> </script>

Configure settings

There are a number of settings you can configure within the script tag shown above for in-app messages:

Set whether or not to hide the status bar. Takes true or false; the default is true.

InAppMessage.hideStatusBar = false;

Turn the default fade animation style on or off. Options are true or false; the default is true.

InAppMessage.animationFade = false;

Set the animation style when the in-app message first appears over, the default is fade. Style options are: from-left, from-right, from-top, from-bottom.

InAppMessage.animationSlide = "from-left";

Lock display orientation. Options are portrait or landscape. By default it will not lock.

InAppMessage.lockOrientation = "portrait";

If your in-app message has a form that requires input you must set this as true; by default it is false.

InAppMessage.requiresTextInput = true;

🚧

The following method must be executed when all configurations above are set:
InAppMessage.init();

Add these settings to your custom HTML as shown below.

<script type="text/javascript">
InAppMessage.hideStatusBar = false;
InAppMessage.animationSlide = "from-left";
InAppMessage.lockOrientation = "portrait";
InAppMessage.init();
</script>

SDK Methods

Close the in-app message

To close your custom in-app message, call the following method. The string argument is an action identifier used for analytics tracking. You can use any label as per your requirement.

InAppMessage.close('close_button');

Perform an action from the in-app message

The action method is the main way to trigger navigation or other behaviours from a button tap. It closes the in-app message and then performs the action.

InAppMessage.action(actionIdentifier, value, mode);

Available modes:

Open a URL in the browser

InAppMessage.action('url_button', 'https://xtremepush.com', 'outside');

Open a deeplink

Use this to navigate to a specific screen in your app. The deeplink string is passed to the native SDK's registered deeplink listener/delegate , and your app must have one registered for this to work.

InAppMessage.action('deeplink_button', 'myapp://home', 'deeplink');

📘

Deeplink handling

The deeplink string is handed off to your app's native deeplink handler. The SDK does not handle navigation directly. On Android, this is your DeeplinkListener and on iOS this is the XP deeplink delegate. If no handler is registered, the deeplink will be silently ignored.

Request push notification permission

Use this to trigger the native OS push permission dialog directly from an in-app button tap. This is typically used to build a push primer, which is a custom in-app message that explains the value of push notifications before the OS prompt appears.

InAppMessage.action('primer_button', '', 'request_push_permission');

📘

Push primer behaviour

The SDK automatically suppresses this in-app message if push permission has already been granted, so it is safe to schedule this campaign without additional conditions. On Android this requires API level 33 (Android 13) or above. The in-app message is suppressed on earlier versions.

Example custom HTML message

Below is an example of a custom HTML in-app message with a URL button, a deeplink button, and a close button:

<body style="background: grey; border: 10px solid blue; padding: 5; margin: 0">
<script type="text/javascript" src="https://api.xtremepush.com/sdk/inapp/v1/lib.js?v=1.0"></script>
<button onclick="InAppMessage.action('url_button', 'https://xtremepush.com', 'outside');">Open Website</button>
<button onclick="InAppMessage.action('deeplink_button', 'myapp://home', 'deeplink');">Go to Home</button>
<button onclick="InAppMessage.close('close_button');">Close</button>
<script type="text/javascript">
InAppMessage.hideStatusBar = false;
InAppMessage.animationSlide = "from-left";
InAppMessage.lockOrientation = "portrait";
InAppMessage.init();
</script>
</body>

Multi-language and variants

It is possible to create a multi-language campaign with different creatives based on the languages selected at the campaign level. It is also possible to do a split test to see which variant has a better engagement. Both options are enabled and configured from the Setup tab.

The languages you have selected, together with the variants selected are shown on the left side of the campaign. To be able to identify with which variant and language you are working, this information is shown on the top of the screen.

This example shows a multi-language campaign for English and Hindi combined with split testing. Currently the content shown is for the English version of variant A.

Actions

The Actions button allows you to Apply a template that has been previously created from Content > Templates to a campaign and to copy the content from a specific language & variant. To copy the content, click on Copy From when you are on the variant and language where you want to apply the content. The system will show the available options to copy from.

Preview your message

The preview area displays the current message view, updated as components change. You can select different sizes for phones and tablets, to show the preview of your in-app message in different screen sizes. Click Custom if you want to preview the message on a different model than the ones available. Enter the desired amount of pixels (width and length).