Custom HTML in-app messages

While our standard in-app messages can be customized in a variety of ways, you can gain even greater control over the look and feel of your campaigns using messages designed and built using HTML, CSS, and JavaScript. With some simple composition, you can unlock custom functionality and branding to match any of your needs.

HTML in-app messages allow for greater control over the look and feel of a message, including the following:

• Custom fonts and styles
• Videos
• Multiple images
• On-click behaviors
• Interactive components
• Custom animations

Custom HTML messages can use the JavaScript Bridge methods to log events, set custom attributes, close the message, and more! Check out our GitHub repository that contains detailed instructions on how to use and customize HTML in-app messages for your needs, and for a set of HTML5 in-app messages templates to help you get started.

JavaScript bridge

HTML in-app messages for Web, Android, iOS, and Swift SDKs support a JavaScript “bridge” to interface with Braze SDK, allowing you to trigger custom Braze actions when users click on elements with links or otherwise engage with your content. These methods exist with the global brazeBridge or appboyBridge variable.

For example, to log a custom attribute and custom event, then close the message, you could use the following JavaScript within your HTML in-app message:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<button id="button">Set Favorite Color</button>
<script>
// Wait for the `brazeBridge` ready event, "ab.BridgeReady"
window.addEventListener("ab.BridgeReady", function(){
  // Event handler when the button is clicked
  document.querySelector("#button").onclick = function(){
    // Track Button 1 clicks for analytics
    // Note: This requires Android SDK v8.0.0, Web SDK v2.5.0, Swift SDK v5.4.0, and iOS SDK v3.23.0
    brazeBridge.logClick("0");
    // Set the user's custom attribute
    brazeBridge.getUser().setCustomUserAttribute("favorite color", "blue");
    // Track a custom event
    brazeBridge.logCustomEvent("completed survey");
    // Send the enqueued data to Braze
    brazeBridge.requestImmediateDataFlush();
    // Close this in-app message
    brazeBridge.closeMessage();
  };
}, false);
</script>

JavaScript Bridge methods

The following JavaScript methods are supported within Braze HTML in-app messages:

Link-based actions

In addition to custom JavaScript, Braze SDKs can also send analytics data with these convenient URL shortcuts. Note that these query parameters and URL schemes are all case sensitive.

Button click tracking (deprecated)

To log button clicks for in-app message analytics, you can add abButtonId as a query parameter to any deep link, redirect URL, or anchor element <a>. Use ?abButtonId=0 to log a “Button 1” click, and ?abButtonId=1 to log a “Button 2” click.

As with other URL parameters, the first parameter should begin with a question mark ?, while subsequent parameters should be separated by an ampersand &.

Example URLs

• https://example.com/?abButtonId=0 - Button 1 click
• https://example.com/?abButtonId=1 - Button 2 click
• https://example.com/?utm_source=braze&abButtonId=0 - Button 1 click with other existing URL parameters
• myApp://deep-link?page=home&abButtonId=1 - Mobile deeplink with Button 2 click
• <a href="https://example.com/?abButtonId=1"> - Anchor element <a> with Button 2 click

Open link in new window (mobile only)

To open links outside your app in a new window, set ?abExternalOpen=true. The message will be dismissed before opening the link.

For deep linking, Braze will open your URL regardless of the value of abExternalOpen.

Open as deeplink (mobile only)

To have Braze handle your HTTP or HTTPS link as a deep link, set ?abDeepLink=true.

When this query string parameter is absent or set to false, Braze will try to open the web link in an internal web browser inside the host app.

Close in-app message

To close an in-app message, you can use the brazeBridge.closeMessage() javascript method.

For example, <a onclick="brazeBridge.closeMessage()" href="#">Close</a> will close the in-app message.

HTML upload with preview

When crafting custom HTML in-app messages, you can preview your interactive content directly in Braze.

The message preview panel of the editor shows a realistic preview that renders the JavaScript included in your message. You can preview and interact with your custom messages from the preview panel by clicking through pagination, submitting forms or surveys, watching JavaScript animations, and more!

SDK requirements

To use the HTML preview for in-app messages, you must upgrade to the following minimum Braze SDK versions:

Creating a campaign

When creating a Custom Code in-app message, choose HTML Upload with Preview as the custom type. If you haven’t previously created custom code in-app messages (live or drafts), this option is automatically applied and you won’t need to make a selection.

Keep in mind that your mobile app users need to upgrade to the supported SDK versions to receive this message. We recommend that you nudge users to upgrade their mobile apps before launching campaigns that depend on newer Braze SDK versions.

Asset files

When creating custom code in-app messages with HTML upload, you can upload campaign assets to the media library to reference in your message.

The following file types are supported for upload:

Braze recommends uploading assets to the media library for two reasons:

1. Assets added to a campaign via the media library allow your messages to be displayed even while the user is offline, or has a poor internet connection.
2. Assets uploaded to Braze can be reused across campaigns.

Adding asset files

You can add new or existing assets to your campaign.

To add new assets to your campaign, use the drag-and-drop section to upload a file. Assets added in this section will also be automatically added to the media library. To add assets that you’ve already uploaded to the media library, select Add from Media Library.

After your assets are added, they will appear in the Assets for this campaign section.

If an asset’s filename matches that of a local HTML asset it will be replaced automatically (for example, cat.png is uploaded and <img src="cat.png" /> exists).

Otherwise, hover over an asset from the list and select Copy to copy the file’s URL to your clipboard. Then paste the copied asset URL into your HTML as you normally would when referencing a remote asset.

HTML editor

Changes you make in the HTML automatically render in the preview panel as you type. Any brazeBridge JavaScript methods you use in your HTML won’t update user profiles while previewing in the dashboard.

You can configure Editor Settings to toggle wrap text, change the font size, or choose a color theme. The code editor includes different color themes for syntax highlighting, which helps you spot potential code errors directly in the message composer and better organize your code (using spaces or tabs—whichever side of that argument you’re on).

Button tracking

You can track performance within your custom code in-app message using the brazeBridge.logClick(button_id) JavaScript method. This allows you to programmatically track “Button 1”, “Button 2”, and “Body Clicks” using brazeBridge.logClick("0"), brazeBridge.logClick("1"), or brazeBridge.logClick(), respectively.

You can track multiple button click events per impression. For example, to close a message and log a Button 2 click, you can use the following:

1
<a href="#" onclick="brazeBridge.logClick('1');brazeBridge.closeMessage()">✖</a>

You can also track new custom button names—up to 100 unique names per campaign. For example, brazeBridge.logClick("blue button") or brazeBridge.logClick("viewed carousel page 3").

Limitations

• You can have up to 100 unique button IDs per campaign.
• Button IDs can have up to 255 characters each.
• Button IDs can only include letters, numbers, spaces, dashes, and underscores.

Backward incompatible changes

1. The most notable incompatible change with this new message type is the SDK requirements. Users whose app SDK does not meet the minimum SDK version requirements will not be shown the message.
   

2. The braze://close deeplink, which was previously supported on mobile apps, has been removed in favor of the JavaScript brazeBridge.closeMessage(). This allows for cross-platform HTML messages, since the web does not support deeplinks.

3. Automatic click tracking, which used ?abButtonId=0 for button IDs, and “body click” tracking on close buttons have been removed. The following code examples show how to change your HTML to use our new click tracking JavaScript methods:

   Before	After
   <a href="braze://close">Close Button</a>	<a href="#" onclick="brazeBridge.logClick();brazeBridge.closeMessage()">Close Button</a>
   <a href="braze://close?abButtonId=0">Close Button</a>	<a href="#" onclick="brazeBridge.logClick('0');brazeBridge.closeMessage()">Close Button</a>
   <a href="app://deeplink?abButtonId=0">Track button 1</a>	<a href="app://deeplink" onclick="brazeBridge.logClick('0')">Track button 1</a>
   <script> location.href = "braze://close?abButtonId=1" </script>	<script> window.addEventListener("ab.BridgeReady", function(){   brazeBridge.logClick("1");   brazeBridge.closeMessage(); }); </script>