In-app content blocks

Display native in-app content blocks based on definitions set up in Engagement using the Flutter SDK

In-app content blocks provide a way to display campaigns within your mobile applications that seamlessly blend with the overall app design. Unlike in-app messages that appear as overlays or pop-ups demanding immediate attention, in-app content blocks display inline with the app's existing content.

You can strategically position placeholders for in-app content blocks within your app. You can customize the behavior and presentation to meet your specific requirements.

📘
Refer to the In-app content blocks user guide for instructions on how to create in-app content blocks in Engagement.

In-app content blocks in the example app

Integration

You can integrate in-app content blocks by adding one or more placeholder views in your app. Each in-app content block must have a Placeholder ID specified in its settings in Engagement. The SDK will display an in-app content block in the corresponding placeholder in the app if the current app user matches the target audience.

Add a placeholder view

Add a placeholder view with the specified placeholderId to your layout:

InAppContentBlockPlaceholder(
  placeholderId: "example_content_block"
)

After the SDK initializes, it will identify any in-app content blocks with matching placeholder ID and select the one with the highest priority to display within the placeholder view.

📘
Refer to in_app_cb_page.dart in the example app for a reference implementation.

👍
Always us descriptive, human-readable placeholder IDs. They are tracked as an event property and can be used for analytics within Engagement.

Tracking

The SDK automatically tracks banner events for in-app content blocks with the following values for the action event property:

show
In-app content block displayed to user.
action
User clicked on action button inside in-app content block. The event also contains the corresponding text and link properties.
close
User clicked on close button inside in-app content block.
error
Displaying in-app content block failed. The event contains an error property with an error message.

❗️
The behavior of in-app content block tracking may be affected by the tracking consent feature, which in enabled mode requires explicit consent for tracking. Refer to the consent documentation documentation for details.

Customization

Prefetch in-app content blocks

The SDK can only display an in-app content block after it has been fully loaded (including its content, any images, and its height). Therefore, the in-app content block may only show in the app after a delay.

You may prefetch in-app content blocks for specific placeholders to make them display as soon as possible.

final _plugin = ExponeaPlugin();
...
final config = ExponeaConfiguration(
    ...
    inAppContentBlockPlaceholdersAutoLoad: ['placeholder_1'],
    ...
);
final configured = await _plugin.configure(config);

Customize action behavior

When an in-app content block action (show, click, close, error) is performed, by default, the SDK tracks the appropriate event and, in case of a button click, opens a link.

You can override or customize this behavior by setting overrideDefaultBehavior parameter to true and setting callbacks on the InAppContentBlockPlaceholder.

The example below calls the original tracking methods. This is recommended but not required.

InAppContentBlockPlaceholder(
  placeholderId: 'example_content_block',
  overrideDefaultBehavior: true,
  onMessageShown: (placeholderId, contentBlock) {
    //track 'show' event.
    _plugin.trackInAppContentBlockShown(placeholderId, contentBlock);
    print("Content block shown: $contentBlock");
  },
  onNoMessageFound: (placeholderId) {
    print('Content block for $placeholderId not found');
    // you may set this placeholder hidden
  },
  onActionClicked: (placeholderId, contentBlock, action) {
    _plugin.trackInAppContentBlockClick(placeholderId, contentBlock, action);

    // content block action has to be handled for given `action.url`
    handleUrlByYourApp(action.url);
  },
  onCloseClicked: (placeholderId, contentBlock) {
    //track 'close' event.
    _plugin.trackInAppContentBlockClose(placeholderId, contentBlock);
    // placeholder may show another content block if is assigned to placeholder ID
  },
  onError: (placeholderId, contentBlock, errorMessage) {
    _plugin.trackInAppContentBlockError(placeholderId, contentBlock, errorMessage);
    // you may set this placeholder hidden and do any fallback
  },
)

Technical limitations of in-app content blocks usage in Flutter apps

In-app content blocks use PlatformViews, where the size is determined by Flutter's widget tree and not by their content size. To mitigate this limitation, the SDK initializes each in-app content block at the beginning with height=1. After it finishes loading the content, it calculates and updates the size.

When using in-app content blocks in scrollable content, we recommend using in-app content blocks in Views, where the state of widgets is maintained even when the widgets are off-screen.

SingleChildScrollView(
  child: Column(
    children: [
      ListItem()
      ...
      InAppContentBlockPlaceholder(
        placeholderId: 'example'
      )
      ...
      ListItem()
    ],
  ),
),

Troubleshooting

This section provides helpful pointers for troubleshooting in-app content block issues.

👍
Enable verbose logging
The SDK logs a lot of information in verbose mode while loading in-app content blocks. When troubleshooting in-app content block issues, first ensure to set the SDK's log level to verbose.

In-app content block not displayed

The SDK can only display an in-app content block after it has been fully loaded (including its content, any images, and its height). Therefore, the in-app content block may only show in the app after a delay.
Always ensure that the placeholder IDs in the in-app content block configuration (in the Engagement web app) and in your mobile app match.