Tutorial: Displaying a Banner by Placement ID
Follow along with the sample code in this tutorial to display Banners using their placement ID. For more general information, see Banners.
Prerequisites
Before you can start this tutorial, verify that your Braze SDK meets the minimum version requirements:
Displaying banners for the Web SDK
We’re piloting this new tutorial format. Tell us what you think — your feedback helps us improve future guides.
1. Enable debugging (optional)
To make troubleshooting easier while developing, consider enabling debugging.
2. Subscribe to Banner events
Use subscribeToBannersEvents() on Web SDK 7.0.0 and later to register a handler. The handler runs when the Banner cache is replayed, reloaded, or updated, or when an error occurs. Inside the handler, read the placement from event.cacheSnapshot.banners. subscribeToBannersUpdates() is the earlier pattern, deprecated as of 7.0.0. For the full list of events, see Event subscriptions.
3. Insert the Banner and handle control groups
Use braze.insertBanner(banner, container) to insert a Banner when it’s returned. To ensure keep your layout clean, hide or collapse Banners that are apart of a control group (for example, when isControl is true).
4. Refresh your Banners
After initializing the SDK, call requestBannersRefresh(["global_banner", ...]) to ensure that Banners are refreshed at the start of each session.
You can also call this function at any time to refresh Banner placements later.
5. Add a container for your Banner
In your HTML, add a new <div> element and give it a short, Banner-related id, such as global-banner-container. Braze will use this <div> to insert your Banner into the page.
Prerequisites
Before you can start this tutorial, verify that your Braze SDK meets the minimum version requirements:
Displaying banners for the Android SDK
We’re piloting this new tutorial format. Tell us what you think — your feedback helps us improve future guides.
1. Enable debugging (optional)
To make troubleshooting easier while developing, consider enabling debugging.
2. Subscribe to Banner events
Use subscribeToBannersEvents() to register a handler that runs when the Banner cache is replayed or updated. BannersCacheSnapshot.banners is a map of placement ID to Banner.
For the full list of events you can receive, see Event subscriptions.
3. Define BannerView in your banners.xml
In banners.xml, declare a <com.braze.ui.banners.BannerView> with app:placementId="PLACEMENT_ID" and set android:layout_height to 0dp. The view stays in the layout with no height until the Banner reports its content height, so the screen does not reserve empty space before a Banner loads.
After a refresh, the SDK updates a BannerView only when that placement’s content changes. Unchanged displayed Banners stay as-is.
4. Update the Banner height
Set heightCallback on the BannerView. The callback receives the Banner height in dp. Apply that height to the view yourself: convert dp to pixels, then set the layout height.
Banner HTML reports its height through a JavaScript interface, so heightCallback can run off the main thread. Update the view inside bannerView.post so the change runs on the main thread.
A height of 0.0 means there is no content to show. The SDK reports 0.0 when the placement has no Banner, the Banner is in a control group, or the Banner was dismissed. Apply 0.0 as well, so the view collapses and stays in the layout for the next Banner.
5. Limit the Banner height
Cap the height you apply. In this example, min(heightDp, 80.0) keeps the Banner at 80 dp or less.
6. Refresh your placements
After initializing the Braze SDK, call requestBannersRefresh(["PLACEMENT_ID"]) to fetch the latest Banner content for that placement.
This call merges into the existing Banner cache. Only the placement IDs you request are added, updated, or removed. Cached Banners for other placements stay in the cache and expire at their original expiry time. If the server returns no Banner for a requested placement, that placement is dropped from the cache.
To use Jetpack Compose, add the com.braze:android-sdk-jetpack-compose artifact to your app module. Use the same version as your other Braze Android SDK dependencies.
1. Enable debugging (optional)
To make troubleshooting easier while developing, consider enabling debugging.
2. Subscribe to Banner events
Call subscribeToBannersEvents and keep the subscriber so you can remove it when the composable leaves the screen. Set hasBannerForPlacement when CacheReplay, CacheLoad, or DataUpdated contains this placement. On ErrorEvent with FeatureDisabled, set hasBannerForPlacement to false.
Banner events arrive on a background thread. Post UI updates to the main thread.
For when each event fires, see Event subscriptions.
3. Refresh your placements
After you register the subscriber, call requestBannersRefresh(["PLACEMENT_ID"]) to fetch the latest Banner content for that placement. Remove the subscriber with removeSingleSubscription when you no longer need it.
4. Only show the Banner after it is in the cache
Show Banner only when hasBannerForPlacement is true. The placement stays out of your layout until the cache contains a Banner for it.
Import com.braze.jetpackcompose.banners.Banner. Other Compose libraries define their own Banner composable.
5. Update the Banner height
Pass heightCallback to Banner. The callback receives the Banner height in dp. Store it in contentHeight and apply it with Modifier.height. Banner leaves sizing to your layout.
heightCallback can run off the main thread. Post the state update to the main thread before you change contentHeight.
A height of 0.0 means there is no content to show and prevents empty spaces in your UI. The SDK reports 0.0 when the placement has no Banner, the Banner is in a control group, or the Banner was dismissed.
6. Limit the Banner height
Cap the height you apply. In this example, min(contentHeight, 80.0) keeps the Banner at 80 dp or less.
Prerequisites
Before you can start this tutorial, verify that your Braze SDK meets the minimum version requirements:
Displaying banners for the Swift SDK
We’re piloting this new tutorial format. Tell us what you think — your feedback helps us improve future guides.
1. Enable debugging (optional)
To make troubleshooting easier while developing, consider enabling debugging.
2. Subscribe to Banner events
Use subscribeToEvents to register a handler that runs when the Banner cache is replayed, reloaded, or updated, or when an error occurs. cacheSnapshot.banners is a dictionary of placement ID to Banner. Keep a strong reference to the returned Braze.Cancellable, because the SDK cancels the subscription when it is deallocated.
For when each event fires, see Event subscriptions.
3. Refresh your placements
After you register your subscription, call requestBannersRefresh(placementIds: ["PLACEMENT_ID"]) to refresh Banner content at the start of each session.
4. Initialize the Banner and provide a callback
Create a BrazeBannerUI.BannerUIView instance with your Braze object and placement ID, and provide a processContentUpdates callback to unhide the Banner and update its height constraint based on the provided content height.
5. Enable Auto Layout constraints
Hide the Banner view by default, then disable autoresizing mask translation to enable Auto Layout constraints.
6. Anchor content and set height constraints
Anchor your main content to the top using Auto Layout, and place the Banner view after it. Pin the Banner’s leading, trailing, and bottom edges to the safe area, and set an initial height constraint of 0 that will be updated when content loads.
1. Enable debugging (optional)
To make troubleshooting easier while developing, consider enabling debugging.
2. Refresh your placements
After initializing the Braze SDK, call requestBannersRefresh(placementIds: ["PLACEMENT_ID"]) to refresh Banner content at the start of each session.
3. Create a view component
Create a reusable SwiftUI view component that displays available Banners and contains your main app content if needed.
4. Subscribe to Banner events
In .onAppear, use subscribeToEvents to register a handler that sets hasBannerForPlacement whenever the Banner cache is replayed, reloaded, or updated. Keep a strong reference to the returned Braze.Cancellable in your state, because the SDK cancels the subscription when it is deallocated.
For when each event fires, see Event subscriptions.
5. Only show BannerView after it loads
To avoid blank space in your UI, only show BrazeBannerUI.BannerView if a Banner is present and the SDK is initialized.
6. Dynamically update Banner height
Use the processContentUpdates callback to fetch the Banner’s content height as soon as it loads. Update your SwiftUI state (contentHeight) and apply a .frame(height:) constraint using the provided height.
7. Limit the Banner height
To ensure your Banner never exceeds the maximum height, apply a .frame(height: min(contentHeight, 80)) modifier. This will keep your UI visually balanced regardless of the Banner’s content.