Skip to content

Custom listeners

This reference article covers custom in-app messaging listeners for your Android or FireOS application.

Before customizing in-app messages with custom listeners, it’s important to understand the BrazeInAppMessageManager, which handles the majority of in-app message handling. As described in step 1 of the in-app message integration guide, it must be registered for in-app messages to function appropriately.

BrazeInAppMessageManager manages in-app message display on Android. It contains helper class instances that help it manage the lifecycle and display of in-app messages. All of these classes have standard implementations and defining custom classes is completely optional. However, doing so can add another level of control over the display and behavior of in-app messages. These customizable classes include:

Custom manager listener

The BrazeInAppMessageManager automatically handles the display and lifecycle of in-app messages. If you require more control over the lifecycle of a message, setting a custom manager listener will enable you to receive the in-app message object at various points in the in-app message lifecycle, allowing you to handle its display yourself, perform further processing, react to user behavior, process the object’s extras, and much more.

Step 1: Implement an in-app message manager listener

Create a class that implements IInAppMessageManagerListener.

The callbacks in your IInAppMessageManagerListener will be called at various points in the in-app message lifecycle.

For example, if you set a custom manager listener when an in-app message is received from Braze, the beforeInAppMessageDisplayed() method will be called. If your implementation of this method returns InAppMessageOperation.DISCARD, that signals to Braze that the in-app message will be handled by the host app and should not be displayed by Braze. If InAppMessageOperation.DISPLAY_NOW is returned, Braze will attempt to display the in-app message. This method should be used if you choose to display the in-app message in a customized manner.

IInAppMessageManagerListener also includes delegate methods for clicks on the message itself or one of the buttons. A common use case would be intercepting a message when a button or message is clicked for further processing.

Step 2: Hook into in-app message view lifecycle methods (optional)

The IInAppMessageManagerListener interface has in-app message view methods called at distinct points in the in-app message view lifecycle. These methods are called in the following order:

  • beforeInAppMessageViewOpened - Called just before the in-app message is added to the activity’s view. The in-app message is not yet visible to the user at this time.
  • afterInAppMessageViewOpened - Called just after the in-app message is added to the activity’s view. The in-app message is now visible to the user at this time.
  • beforeInAppMessageViewClosed - Called just before the in-app message is removed from the activity’s view. The in-app message is still visible to the user at this time.
  • afterInAppMessageViewClosed - Called just after the in-app message is removed from the activity’s view. The in-app message is no longer visible to the user at this time.

For further context, the time between afterInAppMessageViewOpened and beforeInAppMessageViewClosed is when the in-app message view is on screen, visible to the user.

Step 3: Instruct Braze to use your in-app message manager listener

Once your IInAppMessageManagerListener is created, call BrazeInAppMessageManager.getInstance().setCustomInAppMessageManagerListener() to instruct BrazeInAppMessageManager to use your custom IInAppMessageManagerListener instead of the default listener.

We recommend setting your IInAppMessageManagerListener in your Application.onCreate() before any other calls to Braze. This will set the custom listener before any in-app message is displayed.

Altering in-app messages before display

When a new in-app message is received, and there is already an in-app message being displayed, the new message will be put onto the top of the stack and can be displayed at a later time.

However, if there is no in-app message being displayed, the following delegate method in IInAppMessageManagerListener will be called:

1
2
3
4

@Override
public InAppMessageOperation beforeInAppMessageDisplayed(IInAppMessage inAppMessageBase) {
  return InAppMessageOperation.DISPLAY_NOW;
}

1
2
3

override fun beforeInAppMessageDisplayed(inAppMessageBase: IInAppMessage): InAppMessageOperation {
  return InAppMessageOperation.DISPLAY_NOW
}

The InAppMessageOperation() return value can control when the message should be displayed. The suggested usage of this method would be to delay messages in certain parts of the app by returning DISPLAY_LATER when in-app messages would be distracting to the user’s app experience.

InAppMessageOperation return value Behavior
DISPLAY_NOW The message will be displayed
DISPLAY_LATER The message will be returned to the stack and displayed at the next available opportunity
DISCARD The message will be discarded
null The message will be ignored. This method should NOT return null

See InAppMessageOperation.java for more details.

On Android, this is done by calling logClick and logImpression on in-app messages and logButtonClick on immersive in-app messages.

Step 4: Customizing dark theme behavior (optional)

In the default IInAppMessageManagerListener logic, in beforeInAppMessageDisplayed(), the system settings are checked and conditionally enable dark theme styling on the message with the following code:

1
2
3
4
5
6
7

@Override
public InAppMessageOperation beforeInAppMessageDisplayed(IInAppMessage inAppMessage) {
  if (inAppMessage instanceof IInAppMessageThemeable && ViewUtils.isDeviceInNightMode(BrazeInAppMessageManager.getInstance().getApplicationContext())) {
    ((IInAppMessageThemeable) inAppMessage).enableDarkTheme();
  }
  return InAppMessageOperation.DISPLAY_NOW;
}

1
2
3
4
5
6

override fun beforeInAppMessageDisplayed(inAppMessage: IInAppMessage): InAppMessageOperation {
  if (inAppMessage is IInAppMessageThemeable && ViewUtils.isDeviceInNightMode(BrazeInAppMessageManager.getInstance().applicationContext!!)) {
    (inAppMessage as IInAppMessageThemeable).enableDarkTheme()
  }
  return InAppMessageOperation.DISPLAY_NOW
}

If you want to use your own conditional logic, you can call enableDarkTheme at any step in the pre-display process.

Custom view factory

Braze in-app message types are versatile enough to cover most custom use cases. However, if you want to fully define the visual appearance of your in-app messages instead of using a default type, Braze makes this possible by setting a custom view factory.

Step 1: Implement an in-app message view factory

Create a class that implements IInAppMessageViewFactory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class CustomInAppMessageViewFactory implements IInAppMessageViewFactory {
  @Override
  public View createInAppMessageView(Activity activity, IInAppMessage inAppMessage) {
    // Uses a custom view for slideups, modals, and full in-app messages.
    // HTML in-app messages and any other types will use the Braze default in-app message view factories
    switch (inAppMessage.getMessageType()) {
      case SLIDEUP:
      case MODAL:
      case FULL:
        // Use a custom view of your choosing
        return createMyCustomInAppMessageView();
      default:
        // Use the default in-app message factories
        final IInAppMessageViewFactory defaultInAppMessageViewFactory = BrazeInAppMessageManager.getInstance().getDefaultInAppMessageViewFactory(inAppMessage);
        return defaultInAppMessageViewFactory.createInAppMessageView(activity, inAppMessage);
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class CustomInAppMessageViewFactory : IInAppMessageViewFactory {
  override fun createInAppMessageView(activity: Activity, inAppMessage: IInAppMessage): View {
    // Uses a custom view for slideups, modals, and full in-app messages.
    // HTML in-app messages and any other types will use the Braze default in-app message view factories
    when (inAppMessage.messageType) {
      MessageType.SLIDEUP, MessageType.MODAL, MessageType.FULL ->
        // Use a custom view of your choosing
        return createMyCustomInAppMessageView()
      else -> {
        // Use the default in-app message factories
        val defaultInAppMessageViewFactory = BrazeInAppMessageManager.getInstance().getDefaultInAppMessageViewFactory(inAppMessage)
        return defaultInAppMessageViewFactory!!.createInAppMessageView(activity, inAppMessage)
      }
    }
  }
}

Step 2: Instruct Braze to use your in-app message view factory

Once your IInAppMessageViewFactory is created, call BrazeInAppMessageManager.getInstance().setCustomInAppMessageViewFactory() to instruct BrazeInAppMessageManager to use your custom IInAppMessageViewFactory instead of the default view factory.

Implementing a Braze view interface

The slideup in-app message view implements IInAppMessageView. The full and modal type message views implement IInAppMessageImmersiveView. Implementing one of these classes allows Braze to add click listeners to your custom view where appropriate. All Braze view classes extend Android’s View class.

Implementing IInAppMessageView allows you to define a certain portion of your custom view as clickable. Implementing IInAppMessageImmersiveView allows you to define message button views and a close button view.

Custom animation factory

In-app messages have preset animation behavior. Slideup messages slide into the screen; full and modal messages fade in and out. If you want to define custom animation behaviors for your in-app messages, Braze makes this possible by setting up a custom animation factory.

Step 1: Implement an in-app message animation factory

Create a class that implements IInAppMessageAnimationFactory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class CustomInAppMessageAnimationFactory implements IInAppMessageAnimationFactory {

  @Override
  public Animation getOpeningAnimation(IInAppMessage inAppMessage) {
    Animation animation = new AlphaAnimation(0, 1);
    animation.setInterpolator(new AccelerateInterpolator());
    animation.setDuration(2000L);
    return animation;
  }

  @Override
  public Animation getClosingAnimation(IInAppMessage inAppMessage) {
    Animation animation = new AlphaAnimation(1, 0);
    animation.setInterpolator(new DecelerateInterpolator());
    animation.setDuration(2000L);
    return animation;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class CustomInAppMessageAnimationFactory : IInAppMessageAnimationFactory {
  override fun getOpeningAnimation(inAppMessage: IInAppMessage): Animation {
    val animation: Animation = AlphaAnimation(0, 1)
    animation.interpolator = AccelerateInterpolator()
    animation.duration = 2000L
    return animation
  }

  override fun getClosingAnimation(inAppMessage: IInAppMessage): Animation {
    val animation: Animation = AlphaAnimation(1, 0)
    animation.interpolator = DecelerateInterpolator()
    animation.duration = 2000L
    return animation
  }
}

Step 2: Instruct Braze to use your in-app message view factory

Once your IInAppMessageAnimationFactory is created, call BrazeInAppMessageManager.getInstance().setCustomInAppMessageAnimationFactory() to instruct BrazeInAppMessageManager to use your custom IInAppMessageAnimationFactory instead of the default animation factory.

We recommend setting your IInAppMessageAnimationFactory in your Application.onCreate() before any other calls to Braze. This will set the custom animation factory before any in-app message is displayed.

Custom HTML in-app message action listener

The Braze SDK has a default DefaultHtmlInAppMessageActionListener class that is used if no custom listener is defined and takes appropriate action automatically. If you require more control over how a user interacts with different buttons inside a custom HTML in-app message, implement a custom IHtmlInAppMessageActionListener class.

Step 1: Implement a custom HTML in-app message action listener

Create a class that implements IHtmlInAppMessageActionListener.

The callbacks in your IHtmlInAppMessageActionListener will be called whenever the user initiates any of the following actions inside the HTML in-app message:

  • Clicks on the close button
  • Fires a custom event
  • Clicks on a URL inside HTML in-app message
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

public class CustomHtmlInAppMessageActionListener implements IHtmlInAppMessageActionListener {
  private final Context mContext;

  public CustomHtmlInAppMessageActionListener(Context context) {
    mContext = context;
  }

  @Override
  public void onCloseClicked(IInAppMessage inAppMessage, String url, Bundle queryBundle) {
    Toast.makeText(mContext, "HTML In App Message closed", Toast.LENGTH_LONG).show();
    BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false);
  }

  @Override
  public boolean onCustomEventFired(IInAppMessage inAppMessage, String url, Bundle queryBundle) {
    Toast.makeText(mContext, "Custom event fired. Ignoring.", Toast.LENGTH_LONG).show();
    return true;
  }

  @Override
  public boolean onNewsfeedClicked(IInAppMessage inAppMessage, String url, Bundle queryBundle) {
    Toast.makeText(mContext, "Newsfeed button pressed. Ignoring.", Toast.LENGTH_LONG).show();
    BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false);
    return true;
  }

  @Override
  public boolean onOtherUrlAction(IInAppMessage inAppMessage, String url, Bundle queryBundle) {
    Toast.makeText(mContext, "Custom url pressed: " + url + " . Ignoring", Toast.LENGTH_LONG).show();
    BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false);
    return true;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class CustomHtmlInAppMessageActionListener(private val mContext: Context) : IHtmlInAppMessageActionListener {

    override fun onCloseClicked(inAppMessage: IInAppMessage, url: String, queryBundle: Bundle) {
        Toast.makeText(mContext, "HTML In App Message closed", Toast.LENGTH_LONG).show()
        BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false)
    }

    override fun onCustomEventFired(inAppMessage: IInAppMessage, url: String, queryBundle: Bundle): Boolean {
        Toast.makeText(mContext, "Custom event fired. Ignoring.", Toast.LENGTH_LONG).show()
        return true
    }

    override fun onNewsfeedClicked(inAppMessage: IInAppMessage, url: String, queryBundle: Bundle): Boolean {
        Toast.makeText(mContext, "Newsfeed button pressed. Ignoring.", Toast.LENGTH_LONG).show()
        BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false)
        return true
    }

    override fun onOtherUrlAction(inAppMessage: IInAppMessage, url: String, queryBundle: Bundle): Boolean {
        Toast.makeText(mContext, "Custom url pressed: $url . Ignoring", Toast.LENGTH_LONG).show()
        BrazeInAppMessageManager.getInstance().hideCurrentlyDisplayingInAppMessage(false)
        return true
    }
}

Step 2: Instruct Braze to use your HTML in-app message action listener

Once your IHtmlInAppMessageActionListener is created, call BrazeInAppMessageManager.getInstance().setCustomHtmlInAppMessageActionListener() to instruct BrazeInAppMessageManager to use your custom IHtmlInAppMessageActionListener instead of the default action listener.

We recommend setting your IHtmlInAppMessageActionListener in your Application.onCreate() before any other calls to Braze. This will set the custom action listener before any in-app message is displayed:

1

BrazeInAppMessageManager.getInstance().setCustomHtmlInAppMessageActionListener(new CustomHtmlInAppMessageActionListener(context));

1

BrazeInAppMessageManager.getInstance().setCustomHtmlInAppMessageActionListener(CustomHtmlInAppMessageActionListener(context))

Custom view wrapper factory

The BrazeInAppMessageManager automatically handles placing the in-app message model into the existing activity view hierarchy by default using DefaultInAppMessageViewWrapper. If you need to customize how in-app messages are placed into the view hierarchy, you should use a custom IInAppMessageViewWrapperFactory.

Step 1: Implement an in-app message view wrapper factory

Create a class that implements IInAppMessageViewWrapperFactory and returns an IInAppMessageViewWrapper.

This factory is called immediately after the in-app message view is created. The easiest way to implement a custom IInAppMessageViewWrapper is just to extend the default DefaultInAppMessageViewWrapper:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

public class CustomInAppMessageViewWrapper extends DefaultInAppMessageViewWrapper {
  public CustomInAppMessageViewWrapper(View inAppMessageView,
                                       IInAppMessage inAppMessage,
                                       IInAppMessageViewLifecycleListener inAppMessageViewLifecycleListener,
                                       BrazeConfigurationProvider brazeConfigurationProvider,
                                       Animation openingAnimation,
                                       Animation closingAnimation, View clickableInAppMessageView) {
    super(inAppMessageView,
        inAppMessage,
        inAppMessageViewLifecycleListener,
        brazeConfigurationProvider,
        openingAnimation,
        closingAnimation,
        clickableInAppMessageView);
  }

  @Override
  public void open(@NonNull Activity activity) {
    super.open(activity);
    Toast.makeText(activity.getApplicationContext(), "Opened in-app message", Toast.LENGTH_SHORT).show();
  }

  @Override
  public void close() {
    super.close();
    Toast.makeText(mInAppMessageView.getContext().getApplicationContext(), "Closed in-app message", Toast.LENGTH_SHORT).show();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class CustomInAppMessageViewWrapper(inAppMessageView: View,
                                    inAppMessage: IInAppMessage,
                                    inAppMessageViewLifecycleListener: IInAppMessageViewLifecycleListener,
                                    brazeConfigurationProvider: BrazeConfigurationProvider,
                                    openingAnimation: Animation,
                                    closingAnimation: Animation, clickableInAppMessageView: View) : 
    DefaultInAppMessageViewWrapper(inAppMessageView, 
        inAppMessage, 
        inAppMessageViewLifecycleListener, 
        brazeConfigurationProvider, 
        openingAnimation, 
        closingAnimation, 
        clickableInAppMessageView) {

  override fun open(activity: Activity) {
    super.open(activity)
    Toast.makeText(activity.applicationContext, "Opened in-app message", Toast.LENGTH_SHORT).show()
  }

  override fun close() {
    super.close()
    Toast.makeText(mInAppMessageView.context.applicationContext, "Closed in-app message", Toast.LENGTH_SHORT).show()
  }
}

Step 2: Instruct Braze to use your custom view wrapper factory

Once your IInAppMessageViewWrapper is created, call BrazeInAppMessageManager.getInstance().setCustomInAppMessageViewWrapperFactory() to instruct BrazeInAppMessageManager to use your custom IInAppMessageViewWrapperFactory instead of the default view wrapper factory.

We recommend setting your IInAppMessageViewWrapperFactory in your Application.onCreate() before any other calls to Braze. This will set the custom view wrapper factory before any in-app message is displayed:

1

BrazeInAppMessageManager.getInstance().setCustomInAppMessageViewWrapperFactory(new CustomInAppMessageViewWrapper());

1

BrazeInAppMessageManager.getInstance().setCustomInAppMessageViewWrapperFactory(CustomInAppMessageViewWrapper())
  Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!