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 Flutter apps. Besides code samples and instructions, it also contains format-specific recommendations and links to additional resources.

Prerequisite

Follow the process in Quick start to integrate the Yandex Mobile Ads Flutter Plugin.
Make sure you're running the latest Yandex Mobile Ads Flutter 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:

Create and configure a widget for displaying banner ads.
Subscribe to load state and event streams.
Load the ad.

Specifics of adaptive inline banner integration

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.
For adaptive inline banners to work properly, make your app layouts adaptive. Otherwise, your ads might render incorrectly.
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.
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.
To get the size of the ad, use the method BannerAdSize.inline(width, maxAdHeight), which accepts the available width of the ad container and the maximum acceptable ad height as arguments.
The BannerAdSize object calculated using the BannerAdSize.inline(width, maxAdHeight) method contains technical data for choosing the most optimal ad sizes on the backend. The height of an ad may change each time it is loaded. The getCalculatedBannerAdSize() method returns the container's bounds based on width and maxAdHeight, but it doesn’t guarantee the ad’s actual size. To match the size precisely, use a Platform Channel and update the container after the ad loads.

To display banner ads, add AdWidget to your app layout.

Example of adding AdWidget to an app screen layout:

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Align(
      alignment: Alignment.bottomCenter,
      child: AdWidget(bannerAd: banner),
    ),
  );
}

Loading and rendering ads

Once you created and added AdWidget to the app screen, you need to load the ads. Before loading an adaptive inline banner, calculate the ad size for each device.

This is done automatically via the SDK API method: BannerAdSize.inline(width, maxAdHeight).

Pass the ad container width and the maximum acceptable ad height as arguments. We recommend using the full width of the device screen or the width of the parent container. Be sure to consider the padding parameters set in your app and the display's safe area:

BannerAdSize getAdSize() {
  final screenWidth = MediaQuery.of(context).size.width.round();
  return BannerAdSize.inline(width: screenWidth, maxHeight: bannerMaxHeight);
}

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

To track when ads load or fail to load and to monitor an adaptive inline banner's lifecycle events, subscribe to the loadStateStream and events streams on the BannerAd class instance.

You can expand ad request parameters through AdRequest() by passing user interests, contextual page data, location, or other additional info. 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:

class _MyHomePageState extends State<MyHomePage> {
  BannerAd? _banner;
  var isBannerAlreadyCreated = false;

  BannerAdSize _getAdSize() {
    final screenWidth = MediaQuery.of(context).size.width.round();
    return BannerAdSize.inline(width: screenWidth, maxHeight: bannerMaxHeight);
  }

  void _loadAd() {
    final banner = BannerAd(adSize: _getAdSize());

    banner.loadStateStream.listen((state) {
      if (state is BannerAdLoadStateLoaded) {
        // The ad was loaded successfully. Now it will be shown.
      } else if (state is BannerAdLoadStateError) {
        // Ad failed to load with AdRequestError.
        // Attempting to load a new ad from the error handler is strongly discouraged.
      }
    });

    banner.events.listen((event) {
      if (event is BannerAdClickedEvent) {
        // Called when a click is recorded for an ad.
      } else if (event is BannerAdImpressionEvent) {
        // Called when an impression is recorded for an ad.
      }
    });

    banner.load(AdRequest(adUnitId: 'R-M-XXXXXX-Y')); // or 'demo-banner-yandex'
    _banner = banner;
    setState(() {
      isBannerAlreadyCreated = true;
    });
  }

  @override
  initState() {
    super.initState();
    YandexAds.initialize();
    _loadAd();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Align(
        alignment: Alignment.bottomCenter,
        child: isBannerAlreadyCreated ? AdWidget(bannerAd: _banner!) : null,
      ),
    );
  }
}

Releasing resources

When you no longer need the banner, call the destroy() method to release resources:

await _banner?.destroy();
_banner = null;

Testing adaptive inline banner integration

Android

iOS

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 YandexAds class's enableLogging method.

YandexAds.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.

Additional resources

Link to pub.dev.

Was the article helpful?

Ad formats

Adaptive sticky banner

Adaptive inline banner

Prerequisite

Implementation

Specifics of adaptive inline banner integration

Adding an ad widget to the app layout

Loading and rendering ads

Releasing resources

Testing adaptive inline banner integration

Using demo ad units for ad testing

Testing ad integration

Using demo ad units for ad testing

Testing ad integration

Additional resources

Was the article helpful?