In-app message delivery

This article describes in-app message delivery via the Braze SDK, such as manually displaying in-app messages or sending local in-app and exit-intent messages.

Trigger types

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

Delivery semantics

All in-app messages that a user is eligible for are automatically downloaded to the user’s device, or browser upon a session start event and triggered according to the message’s delivery rules. Visit our session lifecycle documentation for more information about the SDK’s session start semantics.

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
braze.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 triggered, you can disable automatic display and register your own display subscribers.

First, find and remove the call to braze.automaticallyShowInAppMessages() from within your loading snippet. Then, create your own logic to custom handle a triggered in-app message, where you show or don’t show the message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
braze.subscribeToInAppMessage(function(inAppMessage) {
  // control group messages should always be "shown"
  // this will log an impression and not show a visible message
  
  if (inAppMessage.isControl) { // v4.5.0+, otherwise use  `inAppMessage instanceof braze.ControlMessage`
     return braze.showInAppMessage(inAppMessage);
  }
  
  // Display the in-app message. You could defer display here by pushing this message to code within 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.
  
  if ( should_show_the_message_according_to_your_custom_logic ) {
      braze.showInAppMessage(inAppMessage);
  } else {
      // do nothing
  }
});

The inAppMessage parameter will be an braze.InAppMessage subclass or an braze.ControlMessage object, 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, braze.showInAppMessage will return false, and the second message will not display.

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 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 braze.SlideUpMessage("Welcome to Braze! This is an in-app message.");
  message.slideFrom = braze.InAppMessage.SlideFrom.TOP;
  braze.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 send these messages, first add an exit intent library, such as this open-source library to your website. Then, use the following code snippet to 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() { braze.logCustomEvent('exit intent'); }
  });