In-app content blocks

In-app content blocks let you display campaigns within your mobile apps that blend seamlessly with your overall app design. Unlike in-app messages that appear as overlays or pop-ups demanding immediate attention, in-app content blocks show inline with your app's existing content. They enrich the user experience without being too intrusive.

You can use content blocks in two formats:

  • Static content blocks: Display a single message that doesn't change.
  • Carousels: Rotate various messages within a single block.

Set up placeholders

You can position placeholders for in-app content blocks within your mobile app. Once you set them up, there's no further need for development involvement.

What happens when there's no active campaign

When you implement a placeholder but don't have any active campaigns for it, the behavior depends on how your development team configures the placeholder:

  • Collapsed placeholder: The placeholder takes up no space and becomes invisible when there's no content to display. Collapsed placeholders can use auto-height functionality to adjust their size dynamically.
  • Fixed placeholder: The placeholder maintains its designated space even when empty, which may result in blank areas in your app layout.

Use case examples

  • Share personalized content at key moments
  • Target and test promotions
  • Onboard new customers

Content block types

Static content blocks

Static content blocks help you deliver a single message that doesn't change. This content block works well for critical announcements or permanent offers within your app.

Carousels

Carousels let you rotate various messages within a single block. Carousels work perfectly for displaying multiple offers or messages without needing extra screen space.

Specify the type of content block (static or carousel) when setting up the SDK. For carousels, create a new UI component called CarouselInAppContentBlockView.

For detailed developer settings, refer to Android or iOS SDK setup documentation.

Set up content blocks

A mobile app developer needs to create placeholder UI views in your mobile app where the in-app content blocks will display. Once these placeholders are established, the technical setup is complete. You manage in-app content blocks through the Bloomreach Engagement app.

Review our documentation on how to set up the mobile SDKs:

Create a template

To find different templates or a blank template, go to Campaigns > In-app personalization.

🚧

Important

Templates marked as Native are only available as In-app messages, not In-app content blocks.

All other templates or blank templates can display in the Visual Builder (default) or HTML Builder.

Visual Builder

The Visual Builder lets you use a drag-and-drop editor. You can create and modify your own templates.

HTML Builder

The HTML Builder lets you customize the HTML of your in-app messages and in-app content blocks. Test your HTML code on a real device before launching your campaign to ensure compatibility across different devices. This step helps identify and resolve potential issues, ensuring a seamless user experience.

Standard HTML and CSS use

Always use standard HTML and CSS. Don't use experimental features or proprietary values.

Forbidden HTML tags and attributes:

  • Tags: head, script, link, iframe, meta, title, body
  • Attributes: onclick, href, and other inline JavaScript attributes

Choose personalization type

Once you've chosen your preferred way of building your campaign, choose which type of in-app personalization you want to create - In-app message (default) or in-app content block (available in the drop-down menu on the left).

Fill the settings

Once you choose the type of in-app personalization and modify it to your business needs, fill in the Settings.

Compared to the settings of In-app messages, a new field was added.

Placeholder ID

This is the ID of the placeholder where you want the campaign to show. You can insert multiple IDs if you want the campaign to show in different placeholders.

The placeholder ID tracks as an event property. If you're using this property further (for example, for campaign analytics), name them according to some logical system rather than random alphanumeric characters..

Multiple in-app content blocks

If you create multiple in-app content blocks with the same placeholder ID, the one with the higher priority will show. If they have the same priority, one will be selected at random.

Specifications

When you switch from an in-app message template to an in-app content block, the Close button (X) stays in the template. This happens because both message types use the same templates.

What this means:

  • The close button will show in your content block in your mobile application.
  • When users tap it, we track a close event, but the content block stays visible.
  • If you set the content block to show "until interaction," it won't appear again after users tap the close button.

📘

Pro tip

Remove close buttons from content block templates since users can't actually close them.

The CSS images and custom fonts from recent SDK versions are also supported.

Fetch in-app content blocks

You can optionally specify a list of placeholders to be fetched in advance when initializing the SDK. This ensures they're ready to display when needed.

You also have the option (but it's not required) to fetch content for a single placeholder at any point while the SDK runs to get the latest updates. For example, something that may change based on your in-session behavior. For more information, review our Mobile SDK documentation.

Tracking

Each in-app message shown to a customer is tracked as a banner event with the same attributes as in any weblayer. In addition, the following attributes unique to in-app personalizations are tracked:

AttributeDescriptionExample
app_versionThe version of the mobile app.2.21.3
device_modelThe device model used.iPhone
device_typeThe type of device used.mobile
os_nameThe name of the operating system used.iOS
os_versionThe version of the operating system used.17.2
placeholderThe ID of the placeholder where the content block was displayed.example_top
platformThe platform used.iOS
sdkThe name of the mobile SDK used by the app.Exponea iOS SDK
sdk_versionThe version of the mobile SDK used by the app.2.21.3
typeThe type of the banner shown ('in-app message' or 'in-app content block').in-app content block

Error messages

If an error occurs while delivering an in-app message to a customer's device, the banner event will have an additional attribute error with an error message as value.

You may encounter the following error messages:

Error messageDescription
"Invalid action definition"The user clicked on a link that isn't listed in our predefined actions.
"Invalid HTML or empty"The provided HTML is either incorrect or missing. This includes cases where an image couldn't be processed or converted to Base64, or the HTML was determined invalid.

If any of the above errors track frequently, that may indicate a problem with the implementation of the Mobile SDK in your app.

Best practices

Images

  • Use an image file format supported by the target platform or platforms.
    • GIF, JPEG, PNG are natively supported by both Android and iOS.
    • WebP and HEIC are newer formats that aren't supported on some Android and iOS versions.
  • Use an appropriate image size and aspect ratio.
    • Don't use images larger than they need to be. Such images will be scaled down to the appropriate size and display normally, but they take up more bandwidth and may lead to a delivery delay.
    • Don't use images whose aspect ratio doesn't match the layout and design of the in-app content block. Such images will be appropriately scaled down to the correct aspect ratio, but they take up more bandwidth and may lead to a delivery delay.

Screen resolutions

Some common screen resolutions for reference:

  • 1284×2778: Found on high-end iOS devices like the iPhone 14 Pro Max.
  • 1440×3200: Found on premium Android devices like the Samsung Galaxy S series.

The Mobile SDKs include the device and OS used in the tracked event properties. You can use this data to analyze which devices and OS versions your customers use.

Limitations

Links in buttons

To add a data-link attribute (which is required for links to work in our SDK) the button or link needs to have a URL filled. When the URL isn't filled, the editor won't generate an <a> tag and the data-link attribute will be missing. This means you need to fill in both the URL and the data-link attribute with the same value.

Performance recommendations

  • When using personalized in-app content blocks (any information from customer profiles or from catalogs), preloading less than ten content blocks is recommended. For better performance, load as many as possible on demand.
  • In-app content blocks targeted for one placeholder should be less than 10.
  • For the best system performance, don't show a unique content block more frequently than once every 5 seconds on a single device.
  • One content block shouldn't be larger than 100kB.

Tracking

If users don't grant tracking consent, we can't track their interactions with content blocks. However, the SDK stores this information locally on their device. This means:

  • Content blocks still follow their display rules (like "show once" or "until interaction").
  • If the local data gets cleared, the content block may show again.
  • This can happen when you call IdentifyCustomer or Anonymize functions, or if events aren't sent fast enough. This behavior may also occur if tracked events aren't sent to the system in a timely manner (for example, due to manual event flushing) or if there are rapid track and identifyCustomer calls.

For detailed setup instructions, check our Mobile SDK documentation.

In-app content blocks generate events similar to banners and weblayers, so your analytics stay consistent across all engagement channels.