Adaptive inline banner

Adaptive inline banners are a flexible format of banner advertising, providing maximum efficiency by optimizing the size of the ad on each device.

This ad type lets developers set a maximum allowable width and height for the ad, though the optimal ad size is still determined automatically. To select the best ad size, built-in adaptive banners use the maximum height rather than the fixed height. That provides room for improving performance.

Typically, this format is used in feed-based apps or contexts where it's acceptable to primarily focus user attention on ads.

Appearance

This guide covers the process of integrating adaptive inline banners into Compose Multiplatform apps. Besides code samples and instructions, it also contains format-specific recommendations and links to additional resources.

Prerequisite

  1. Follow the process in Quick start to integrate the Yandex Mobile Ads Compose Multiplatform Plugin.
  2. Make sure you're running the latest Yandex Mobile Ads Compose Multiplatform Plugin version. If you're using mediation, make sure you're running the latest version of the unified build.

Implementation

Key steps for integrating adaptive inline banners:

  • Add the Banner composable to your UI and pass BannerAdSize.Inline with the container width and maximum height.
  • Set callback functions for the ad lifecycle events through BannerEvents.

Specifics of adaptive inline banner integration

  1. If the onAdFailedToLoad callback returns an error, don't try to load a new ad again. If there's no other option, limit the number of ad load retries. This will help avoid constant unsuccessful requests and connection issues if there are limitations.

  2. For adaptive inline banners to work properly, make your app layouts adaptive. Otherwise, your ads might render incorrectly.

  3. Adaptive inline banners work best when utilizing the full available width. In most cases, this will be the full width of the device screen. Be sure to consider the padding parameters set in your app and the display's safe area.

  4. Adaptive inline banners are designed to be placed in scrollable content. Their height can be the same as the device screen or limited by the maximum height, depending on the API.

  5. To describe the banner size, use BannerAdSize.Inline(width, maxHeight), which accepts the available width of the ad container and the maximum acceptable ad height.

  6. The BannerAdSize value built with BannerAdSize.Inline(width, maxHeight) carries technical data for choosing optimal sizes on the backend. The rendered height may change on each load. To align layout tightly with the creative, measure the container after load if your product requires pixel‑accurate placement.

Adding a banner to the layout

Use the Banner composable where the inline banner should appear (for example, inside a scrollable column in the feed).

Example of placing a banner on a screen:

@Composable
fun BannerSlot(adRequest: AdRequest, containerWidth: Int, maxHeight: Int) {
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = containerWidth, maxHeight = maxHeight),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = { /* ad loaded */ },
            onAdFailedToLoad = { error -> /* handle error */ },
            onAdClicked = { /* ad clicked */ },
            onImpression = { data -> /* impression tracked */ },
        ),
    )
}

Loading and rendering ads

The Banner composable loads and refreshes the ad for the given AdRequest automatically when it enters composition.

Pass the ad container width and the maximum acceptable height to BannerAdSize.Inline. We recommend using the full width of the parent or the screen, accounting for padding and safe areas. You can derive width from BoxWithConstraints or your own layout measurement:

BoxWithConstraints(modifier = Modifier.fillMaxWidth()) {
    val widthDp = maxWidth.value.toInt()
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = widthDp, maxHeight = bannerMaxHeightDp),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(/* ... */),
    )
}

To load ads, you need the ad unit ID you obtained in the Yandex Advertising Network interface (adUnitId).

To enable notifications when ads load or fail to load and to track an adaptive inline banner's lifecycle events, use BannerEvents as in the example above.

You can extend requests with AdRequest (for example targeting, parameters, preferredTheme). Extra context added to ad requests can greatly improve the ad quality. Read more in the Ad Targeting section.

The following example shows how to load an adaptive inline banner. Once loaded, the banner is displayed automatically:

@Composable
fun InlineBanner(adUnitId: String) {
    Banner(
        adRequest = AdRequest(adUnitId = adUnitId),
        adSize = BannerAdSize.Inline(width = 320, maxHeight = 50),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = {
                // The ad was loaded successfully and will be shown.
            },
            onAdFailedToLoad = { error ->
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
            },
            onAdClicked = {
                // Called when a click is recorded for an ad.
            },
            onImpression = { impressionData ->
                // Called when an impression is recorded for an ad.
            },
        ),
    )
}

Use 'demo-banner-yandex' as adUnitId while integrating; replace it with your real unit before release.

Releasing resources

When the user navigates away, remove Banner from composition (or stop rendering it). That disposes the underlying platform view. Do not keep a reference to a hidden banner solely to reuse it; build a new Banner with a fresh AdRequest when the slot should appear again.

Testing adaptive inline banner integration

Using demo ad units for ad testing

We recommend using test ads to test your adaptive inline banner integration and your app itself.

To guarantee that test ads are returned for every ad request, we created a special demo ad placement ID. Use it to check your ad integration.

Demo adUnitId: demo-banner-yandex.

Warning

Before publishing your app in the store, make sure to replace the demo ad placement ID with a real one obtained from the Yandex Advertising Network interface.

You can find the list of available demo ad placement IDs in the Demo ad units for testing section.

Testing ad integration

You can test your adaptive inline banner integration using the SDK's built-in analyzer.

The tool makes sure your ads are integrated properly and outputs a detailed report to the log. To view the report, search for the “YandexAds” keyword in the Logcat tool for Android app debugging.

adb logcat -v brief '*:S YandexAds'

If the integration is successful, you'll see this message:

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully

If you're having problems integrating banner ads, you'll get a detailed report on the issues and recommendations for how to fix them.

Using demo ad units for ad testing

We recommend using test ads to test your ad integration and your app itself.

To guarantee that test ads are returned for every ad request, we created a special demo ad placement ID. Use it to check your ad integration.

Demo adUnitId: demo-banner-yandex.

Warning

Before publishing your app to the store, make sure you replace the demo ad unit ID with a real one obtained from the Yandex Advertising Network interface.

You can find the list of available demo ad placement IDs in the Demo ad units for testing section.

Testing ad integration

You can test your ad integration using the native Console tool.

To view detailed logs, call the YMAMobileAds class's enableLogging method.

YMAMobileAds.enableLogging()

To view SDK logs, go to the Console tool and set Subsystem = com.mobile.ads.ads.sdk. You can also filter logs by category and error level.

If you're having problems integrating ads, you'll get a detailed report on the issues and recommendations for how to fix them.

Previous
Ad formats
Next
Adaptive sticky banner