Articles in this section

In-App Messages on Android

Android In-App

# In this article

# Default behavior

By default, when an in-app message arrives from the server, the SDK automatically shows it if the app is in the foreground. If an in-app message is already showing when the new message arrives, the new message will be shown 30 seconds after the currently displayed in-app message closes (see how to change this default value below).
Once an in-app message is shown, it will be "consumed" from the server queue and removed from the local queue as well. There is no need to write any code to get this default behavior.

# Overriding whether to show or skip a particular in-app message

An incoming in-app message triggers a call to the onNewInApp method of IterableConfig.inAppHandler (an IterableInAppHandler object). To override the default behavior, set inAppHandler in IterableConfig to a custom class that overrides the onNewInApp method. onNewInApp should return InAppResponse.SHOW to show the incoming in-app message or InAppResponse.SKIP to skip showing it.

TIP

To determine the priority of an IterableInAppMessage object, call its getPriorityLevel method. You can use this priority to help determine whether or not to display it.

class MyInAppHandler implements IterableInAppHandler {
    @Override
    public InAppResponse onNewInApp(IterableInAppMessage message) {
        if (/* add conditions here */) {
            return InAppResponse.SHOW;
        } else {
            return InAppResponse.SKIP;
        }
    }
}

// ...

IterableConfig config = new IterableConfig.Builder()
  .setPushIntegrationName("myPushIntegration")
  .setInAppHandler(new MyInAppHandler())
  .build();
IterableApi.initialize(context, "<your-api-key>", config);

# Getting the local queue of in-app messages

The SDK keeps the local in-app message queue in sync by checking the server queue every time the app goes into foreground, and via silent push messages that arrive from Iterable servers to notify the app whenever a new in-app message is added to the queue.

To access the in-app message queue, call IterableApi.getInstance().getInAppManager().getMessages(). To show a message, call IterableApi.getInstance().getInAppManager().showMessage(message).

// Get the in-app messages list
IterableInAppManager inAppManager = IterableApi.getInstance().getInAppManager();
List<IterableInAppMessage> messages = inAppManager.getMessages();

// Show an in-app message 
inAppManager.showMessage(message);

// Show an in-app message without consuming (not removing it from the queue)
inAppManager.showMessage(message, false)

The SDK handles in-app message buttons and links as follows:

  • If the URL of the button or link uses the action:// URL scheme, the SDK passes the action to IterableConfig.customActionHandler.handleIterableCustomAction(). If customActionHandler (an IterableCustomActionHandler object) has not been set, the action will not be handled.

    For the time being, the SDK will treat itbl:// URLs the same way as action:// URLs. However, this behavior will eventually be deprecated (timeline TBD), so it's best to migrate to the action:// URL scheme as it's possible to do so.

  • The iterable:// URL scheme is reserved for action names predefined by the SDK. If the URL of the button or link uses an iterable:// URL known to the SDK, it will be handled automatically and will not be passed to the custom action handler. For example, buttons or links with URL iterable://dismiss dismiss an in-app message and create in-app click and in-app close events.

  • The SDK passes all other URLs to IterableConfig.urlHandler.handleIterableURL(). If urlHandler (an IterableUrlHandler object) has not been set, or if it returns false for the provided URL, the URL will be opened by the system (using a web browser or other application, as applicable).

# Configuring how in-app messages interact with system bars (SDK v3.8.0 and above)

By default, Iterable's Android SDK draws in-app messages edge-to-edge, with content extending behind the status bar and navigation bar. This was the only behavior in SDK versions 3.6.1 through 3.7.0.

Starting with SDK version 3.8.0, you can configure how in-app messages interact with system bars by setting IterableInAppDisplayMode on IterableConfig. This setting applies globally to all in-app messages displayed by the SDK.

The available modes are:

  • FORCE_EDGE_TO_EDGE (default) — Forces in-app messages to display edge-to-edge, drawing content behind the status bar and navigation bar. This preserves the behavior of previous SDK versions.
  • FOLLOW_APP_LAYOUT — Matches the host app's current layout configuration. If your app is edge-to-edge, in-app messages display edge-to-edge; if your app respects system bar bounds, so do in-app messages.
  • FORCE_FULLSCREEN — Hides the status bar entirely while in-app messages are displayed. Uses the legacy FLAG_FULLSCREEN on API levels below 30 and WindowInsetsController on API 30 and above.
  • FORCE_RESPECT_BOUNDS — Ensures in-app content never draws behind the status bar or navigation bar, keeping UI elements like the close button always accessible.

To configure the display mode, call setInAppDisplayMode() on IterableConfig.Builder:

IterableConfig config = new IterableConfig.Builder()
    .setInAppDisplayMode(IterableInAppDisplayMode.FOLLOW_APP_LAYOUT)
    .build();
IterableApi.initialize(context, "<your-api-key>", config);

TIP

If the close button (or other interactive elements) in your fullscreen in-app messages is being obscured by the status bar, switch to FOLLOW_APP_LAYOUT or FORCE_RESPECT_BOUNDS.

# Changing the display interval between in-app messages

To customize the time delay between successive in-app messages, set inAppDisplayInterval on IterableConfig to an appropriate value in seconds. The default value is 30 seconds.

# Pausing the display of in-app messages (SDK v3.2.6 and above)

In certain areas of your app, you may want to prevent interruptions. To pause the display of in-app messages, call the following method:

Kotlin

IterableApi.getInstance().inAppManager.setAutoDisplayPaused(true)

Java

IterableApi.getInstance().getInAppManager().setAutoDisplayPaused(true);

With this done, the app will not automatically display new in-app messages. However, it will keep the local queue of in-app messages in sync.

TIP

While in-app message display has been paused, you can still call the showMessage method on IterableInAppManager to manually display messages.

To resume the display of in-app messages from your app's queue, call setAutoDisplayPaused(false).

# Further reading

User guides:

Developer documentation:

Related articles