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. 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.
4. Define BannerView in your banners.xml
In banners.xml, declare a <com.braze.ui.banners.BannerView> element with app:placementId="PLACEMENT_ID". Braze will use this element to insert your Banner into your UI.
After a refresh, the SDK updates a BannerView only when that placement’s content changes. Unchanged displayed Banners stay as-is.
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.