Skip to content

Banner Ads

Jump to bottom
Dmytro Uzhva edited this page Dec 10, 2024 · 10 revisions

⚡ Before you start
Make sure you have correctly Initialize SDK.

Banner ads occupy a spot within an app's layout, either at the top or bottom of the device screen. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.

This guide shows you how to integrate banner ads from CAS into a Flutter app. Banner ads are displayed in BannerWidget objects from module CleverAdsSolutions, so the first step toward integrating banner ads is to include a BannerWidget in your view hierarchy. This is typically done either with the widget tree.

Add to the widget tree

The first step toward displaying a banner is to place BannerWidget in the widget tree where you'd like to display it. The easiest way to do this is to add one to the desired part of your widget layout. Here's an example showing how to add a BannerWidget in a Flutter application:

final GlobalKey<BannerWidgetState> _bannerKey = GlobalKey();

@override
Widget build(BuildContext context) {
  return BannerWidget(
    key: _bannerKey,
    size: AdSize.banner,
    isAutoloadEnabled: true,
    refreshInterval: 30,
    listener: BannerListener(),
  );
}

Note the following attributes:

  • key - Set the key to access the widget's state.
  • size - Set the ad size you'd like to use.
    See the banner size section below for details.

Ad size

Size in dp (WxH) Description Availability AdSize
320x50 Standard Banner Phones and Tablets banner
728x90 IAB Leaderboard Tablets leaderboard
300x250 IAB Medium Rectangle Phones and Tablets mediumRectangle
320x50 or 728x90 Smart Banner Phones and Tablets getSmartBanner()
Full width x ≥32 Inline banner Phones and Tablets getInlineBanner()
Adaptive Adaptive banner Phones and Tablets getAdaptiveBanner()
Adaptive Adaptive banner Phones and Tablets getAdaptiveBannerInScreen()

❕Typically, Smart Banners on phones have a banner size. Or on tablets a leaderboard size.

Adaptive banners

Adaptive banners are the next generation of responsive ads, maximizing performance by optimizing ad size for each device.
To pick the best ad size, adaptive banners use fixed aspect ratios instead of fixed heights. This results in banner ads that occupy a more consistent portion of the screen across devices and provide opportunities for improved performance.

When implementing adaptive banners in your app, keep the following points in mind:

  • The adaptive banner sizes are designed to work best when using the full available width. In most cases, this will be the full width of the screen of the device in use. Be sure to take into account applicable safe areas.
  • The height is never larger than the lesser of 15% of the device's height or 90 density independent pixels and never smaller than 50 density independent pixels.
  • The width cannot be less than 300 density independent pixels.

Use the appropriate static methods on the ad size class to get an adaptive AdSize object.

// Get adaptive size with width parameter:
adSize = AdSize.getAdaptiveBanner(maxWidthDPI);
// Get adaptive size in full screen width:
adSize = AdSize.getAdaptiveBannerInScreen();

Warning

After changing the screen orientation, the banner should get a new size. Therefore, you should retrieve the size inside the build() function of your screen's widget to update the size when rebuilding the widget tree.

Ad events

To further customize the behavior of your ad, you can hook into a number of events in the ad's lifecycle: loading, opening, closing, and so on. To get lifecycle events of ad, you could extend AdViewListener class and pass it to listener property or use state of banner.

// Pass listener to widget property
BannerWidget(
  listener: BannerListener(),
);
// OR pass listener to widget state
bannerKey.currentState?.setAdListener(BannerListener());

class BannerListener extends AdViewListener {
  @override
  void onAdViewPresented() {
    // Called when the ad presented.
  }

  @override
  void onClicked() {
    // Called when the user clicks on the Ad
  }

  @override
  void onFailed(String? message) {
    // Сalled when an error occurred with the ad.
  }

  @override
  void onImpression(AdImpression? adImpression) {
    // Called when the ad view did present for user with `AdMetaData` about the impression.
  }

  @override
  void onLoaded() {
    // Called when the ad loaded and ready to present.
  }
}

Note

Read more about event onAdViewPresented with Impression level data.

Autoload Banner Ad

A isAutoloadEnabled() value that determines whether autoloading of ads in the receiver is enabled.
If enabled, you do not need to call the loadNextAd() method from next section to load ads.
To disable autoload, simply pass false to isAutoloadEnabled property or using the following method:

// Pass value to widget property
BannerWidget(
  isAutoloadEnabled: false,
);
// OR pass value to widget state
bannerKey.currentState?.setAutoloadEnabled(false);

By default disabled if global state AdsSettings.loadingMode is LoadingManagerMode.Manual. And changes will override global state of AdsSettings.loadingMode for specific Banner View.

Load Banner Ad

You can use load regardless of the isAutoloadEnabled() value for interrupt ad impression and load next ad.

bannerKey.currentState?.loadNextAd();

Warning

Calling the loadNextAd() method if isAutoloadEnabled() is active will cause the current ad to be lost and a new ad to start loading.

Banner refresh rate

An ad unit’s automatic refresh rate determines how often a new ad request is generated for that ad unit.
We recommended using refresh rate 30 seconds. However, you can choose any value you want longer than 10 seconds.

If you want to use custom refresh interval, just pass seconds to refreshInterval property or use the following method:

// Pass value to widget property
BannerWidget(
  refreshInterval: 30,
);
// OR pass value to widget state
bannerKey.currentState?.setRefreshInterval(interval);
// OR disable auto refresh ads
bannerKey.currentState?.disableAdRefresh();

Note

  • Ad requests should not be made when the device screen is turned off.
  • The isAutoloadEnabled() has no effect on refreshing the banner ad.

Check Ad Availability

You can ask for the ad availability directly by calling the following function:

bool bannerLoaded = bannerKey.currentState?.isAdReady();

Sample use case

🔗 Done! What’s Next?

Android SDK | iOS SDK | Unity SDK | Flutter SDK | App-ads.txt | cleveradssolutions.com | [email protected]

Integration

Implementation

Test Your Integration

Clone this wiki locally