In-App Messaging

In-App Messages are great for creating unobtrusive calls to action, notifying people of new content in the News Feed and driving them toward it, or communicating with users who have push turned off. They are also effective for other content that isn’t time-sensitive enough to warrant a push notification, or permanent enough to warrant a News Feed item. You can find a detailed explanation of in-app message behavior on Braze Academy.

Integration

By default, in-app messages are automatically displayed as part of our recommended integration instructions. Additional customization can be done by following the steps in this guide.

In-App Message Types

Braze currently offers the following default in-app message types: Slideup, Modal, and Full and HTML. Each in-app message type is customizable across content, images, icons, click actions, analytics, display, and delivery.

All in-app messages inherit their prototype from appboy.ab.InAppMessage, which defines basic behavior and traits for all in-app messages. The protypical subclasses are appboy.ab.SlideUpMessage, appboy.ab.ModalMessage, appboy.ab.FullScreenMessage, and appboy.ab.HtmlMessage.

Slideup In-App Messages

SlideUp in-app messages are so-named because traditionally on mobile platforms they “slide up” or “slide down” from the top or bottom of the screen. In the Braze Web SDK, these messages are actually displayed as more of a Growl or Toast style notification, to align with the web’s dominant paradigm. They cover a small portion of the screen and provide an effective and non-intrusive messaging capability.

Slideup Example

Modal in-app messages appear in the center of the screen and are framed by a translucent panel. Useful for more critical messaging, they can be equipped with up to two click action and analytics enabled buttons.

Modal Example

Full In-App Messages

Full in-app messages are useful for maximizing the content and impact of your user communication. On narrow browser windows (e.g. the mobile web), full in-app messages take up the entire browser window. On larger browser windows, full in-app messages appear similarly to modal in-app messages. The upper half of a full in-app message contains an image and the lower half allows up to eight lines of text as well as up to two click action and analytics enabled buttons

Full Example

HTML In-App Messages

HTML in-app messages are useful for creating fully customized user content. User-defined HTML is displayed in an iframe and may contain rich content, such as images, fonts, videos, and interactive elements, allowing for full control over message appearance and functionality. These support a Javascript appboyBridge interface to call methods on the Braze Web SDK from within your HTML, see Best Practices for more details.

To enable HTML in-app messages, your SDK integration must supply the enableHtmlInAppMessages initialization option to Braze, e.g. appboy.initialize('YOUR-API_KEY', {enableHtmlInAppMessages: true}). This is for security reasons - HTML in-app messages can execute javascript so we require a site maintainer to enable them.

The following example shows a paginated HTML in-app message:

HTML5 Example

In-App Message Delivery

In-App Messages (Triggered)

The following documentation refers to Braze’s In-App Messaging product, aka “triggered in-app messages,” which are branded as highlighted below in the “Create Campaign” drop-down:

In-App Messaging Composer

You may also refer to the documentation for our deprecated Original In-App Messaging product.

Trigger Types

Our in-app message product allows you to trigger in-app message display as a result of several different event types: Any Purchase, Specific Purchase, Session Start, Custom Event, Push Click. Furthermore, Specific Purchase and Custom Event triggers can contain robust property filters.

Delivery Semantics

All in-app messages that a user is eligible for are automatically delivered to the user upon a session start event. For more information about the SDK’s session start semantics, see our session lifecycle documentation.

Minimum Time Interval Between Triggers

By default we rate limit in-app messages to once every 30 seconds to ensure a quality user experience. To override this value, you can pass the minimumIntervalBetweenTriggerActionsInSeconds configuration option to your initialize function.

1
2
// Sets the minimum time interval between triggered in-app messages to 5 seconds instead of the default 30
appboy.initialize('YOUR-API-KEY', { minimumIntervalBetweenTriggerActionsInSeconds: 5 })

Manual In-App Message Display

If you don’t want your site to immediately display new in-app messages when they’re received, you can disable automatic display and register your own display subscribers. First, find and remove the call to appboy.display.automaticallyShowNewInAppMessages() from within your loading snippet. Then, create your own subscriber:

1
2
3
4
5
6
7
8
9
appboy.subscribeToNewInAppMessages(function(inAppMessages) {
  // Display the first in-app message. You could defer display here by pushing this message to code within in your own application.
  // If you don't want to use Braze's built-in display capabilities, you could alternatively pass the in-app message to your own display code here.
  appboy.display.showInAppMessage(inAppMessages[0]);

  // Return an array with any remaining, unhandled messages to Braze's internal queue.
  // These will be part of the inAppMessages param the next time this subscriber is invoked.
  return inAppMessages.slice(1);
});

The inAppMessages parameter will be an array of appboy.ab.InAppMessage subclass or appboy.ab.ControlMessage objects, each of which has various lifecycle event subscription methods. See the JSDocs for full documentation.

Only one Modal or Full in-app message can be displayed at a given time. If you attempt to show a second Modal or Full message while one is already showing, appboy.display.showInAppMessage will return false, and the message will automatically be returned to Braze’s internal queue, where it will part of the inAppMessages array parameter the next time your subscriber is invoked.

Local In-App Messages

In-app messages can also be created within your site and displayed locally in real-time. All customization options available on the dashboard are also available locally. This is particularly useful for displaying messages that you wish to trigger within the app in real-time. However, analytics on these locally-created messages will not be available within the Braze dashboard.

1
2
3
4
  // Displays a slideup type in-app message.
  var message = new appboy.ab.SlideUpMessage("Welcome to Braze! This is an in-app message.");
  message.slideFrom = appboy.ab.InAppMessage.SlideFrom.TOP;
  appboy.display.showInAppMessage(message);

Exit-Intent Messages

Exit-intent in-app messages appear when visitors are about to navigate away from your site. They provide another opportunity to communicate important information to users, while not interrupting their experience on your site. To be able to send these messages, first reference the open-source library with the code below, which will log ‘exit intent’ as a custom event. In-app message campaigns can then be created in the dashboard using ‘exit intent’ as the trigger custom event.

1
2
3
  var _ouibounce = ouibounce(false, {
    callback: function() { appboy.logCustomEvent('exit intent'); }
  });

Customization

Key-Value Pair Extras

In-app message objects may carry key-value pairs as their extras property. These are specified on the dashboard under “Additional Message Settings” when creating an in-app message campaign. These can be used to send data down along with an in-app message for further handling by your site. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
appboy.subscribeToNewInAppMessages(function(inAppMessages) {
  if (inAppMessages[0] instanceof appboy.ab.InAppMessage) {
    var extras = inAppMessages[0].extras;
    for (var key in extras) {
      if (data.hasOwnProperty(key)) {
         console.log("key: " + key + ", value: " + extras[key]);
      }
    }
  }

  appboy.display.showInAppMessage(inAppMessages[0]);
  return inAppMessages.slice(1);
});

Custom Styling

Braze UI elements come with a default look and feel that matches the composers within the Braze Dashboard and aims for consistency with other Braze mobile platforms. Braze’s default styles are defined in CSS within the Braze SDK. By overriding selected styles in your application, it is possible to customize our standard in-app message types with your own background images, font families, styles, sizes, animations, and more. For instance, the following is an example override that will cause a in-app messages’ headers to appear italicized:

1
2
3
  body .ab-in-app-message .ab-message-header {
    font-style: italic;
  }

See the JSDocs for more information.

Troubleshooting

Troubleshooting Scenarios

Expected In-App Message Did Not Display

Most in-app message issues can be broken down into two main categories: delivery and display. To troubleshoot why an expected in-app message did not display on your device, you should first ensure that the in-app message was delivered to the device, then troubleshoot message display.

Impressions Are Lower Than Expected

Triggers take time to sync to the device on session start, so there can be a race condition if users log an event or purchase right after they start a session. One potential workaround could be changing the campaign to trigger off of session start, then segmenting off of the intended event or purchase. Note that this would deliver the in-app message on the next session start after the event has occurred.

In-App Message Delivery

The SDK requests in-app messages from Braze’s servers on session start. To check if in-app messages are being delivered to your device, you’ll need to ensure that in-app messages are being both requested by the SDK and returned by Braze’s servers.

Check If Messages Are Requested and Returned

  1. Add yourself as a test user on the Dashboard.
  2. Set up an in-app message campaign targeted at your user.
  3. Ensure that a new session occurs in your application.
  4. Use the Event User Logs to check that your device is requesting in-app messages on session start. Find the SDK Request associated with your test user’s session start event.
    • If your app was meant to request triggered In-App Messages, you should see trigger in the Requested Responses field under Response Data.
    • If your app was meant to request Original In-App Messages, you should see in_app in the Requested Responses field under Response Data.
  5. Use the Event User Logs to check if the correct in-app messages are being returned in the Response Data.

In-App Message

Troubleshoot Messages Not Being Requested

If your in-app messages are not being requested, your app might not be tracking sessions correctly, as in-app messages are refreshed upon session start. Also be sure that your app is actually starting a session based on your app’s session timeout semantics:

Session Start

Troubleshoot Messages Not Being Returned

If your in-app messages are not being returned, you’re likely experiencing a campaign targeting issue:

  • Your segment does not contain your user.
    • Check your user’s Engagement tab to see if the correct segment appears under Segments.
  • Your user has previously received the in-app message and was not re-eligible to receive it again.
    • Check the campaign re-eligibility settings under the Delivery tab of the Campaign Composer and make sure the re-eligibility settings align with your testing setup.
  • Your user hit the frequency cap for the campaign.
  • If there was a control group on the campaign, your user may have fallen into the control group.
    • You can check if this has happened by creating a segment with a “Received Campaign Variant” filter, where the campaign variant is set to “Control”, and checking if your user fell into that segment.
    • When creating campaigns for integration testing purposes, make sure to opt-out of adding a control group.

In-App Message Display

If your app is successfully requesting and receiving in-app messages but they are not being shown, some device-side logic may be preventing display:

  • Triggered in-app messages are rate-limited based on the minimum time interval between triggers, which defaults to 30 seconds.
  • If you have custom in-app message handling through appboy.subscribeToNewInAppMessages, check that subscription to ensure it is not affecting in-app message display.
WAS THIS PAGE HELPFUL?