Banner Ads - cleveradssolutions/CAS-Flutter GitHub Wiki

Banner ad units display rectangular ads that occupy a portion of an app's layout. They can refresh automatically after a set period of time. This means users view a new ad at regular intervals, even if they stay on the same screen in your app. They're also the simplest ad format to implement.

This guide shows you how to integrate banner ads from CAS into an Android app. Banner ads are displayed in CASBannerView objects, so the first step toward integrating banner ads is to include a CASBannerView in your view hierarchy. This is typically done either with the layout or programmatically.

flowchart TD

A[isAutoloadEnabled] -->|auto| L((load))
RI[RefreshInterval] -->|delay| L
L -->|success| R([onAdViewLoaded])
L -->|fail| F([onAdViewFailed])
F -->|delay| A
R --> RL[isLoaded]
S((addView)) --> RL
RL --> C([onAdViewClicked])
RL -->|success| I([onAdImpression])
RL -->|fail| A
I --> RI

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,
    casId: _casId,
    size: AdSize.banner,
  );
}

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.

On create BannerWidget you should set CAS ID to the ad view:

BannerWidget(
  casId: _casId,
  ...
);

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:
LayoutBuilder(builder: (_, BoxConstraints constraints) {
  return BannerWidget(
    size: AdSize.getAdaptiveBanner(constraints.maxWidth),
    ...
  );
});
// Get adaptive size in full screen width:
BannerWidget(
  size: 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.

Listen Ad events

To further customize the behavior of your ad, you can hook onto a number of events in the ad's lifecycle: loading, clicking, and so on. You can listen for these events through the AdViewListener interface. To use an AdViewListener with Banner View, call the setAdListener() method before loading the 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.

Load Banner Ad

Once the ad view is in place, the next step is to load an ad. That's done with the load() method in the BannerWidgetStateclass.

_bannerKey.currentState?.load();

Autoload Ad mode

If enabled, the ad will automatically load new content when the current ad is dismissed or completed. Additionally, it will automatically retry loading the ad if an error occurs during the loading process.

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

By default enabled.

Ad refresh interval

The ad view’s automatic refresh interval determines how often a new ad request is generated for that ad view. You have the option to set a custom refresh interval longer than 10 seconds or to disable the Automatic refresh option for the ad view.

Change the banner automatic refresh interval using the following method:

// Pass value to widget property
BannerWidget(
  refreshInterval: 30,
);
// OR pass value to widget state
_bannerKey.currentState?.setRefreshInterval(interval);

We recommend using optimal automatic refresh interval 30 seconds, by default.

To disable refresh ad use following method:

_bannerKey.currentState?.disableAdRefresh();

[!NOTE]

• The automatic refresh occurs only if the banner is visible on screen.
• The isAutoloadEnabled has no effect on refreshing the banner ad.

Release ad resource

It is important to destroy() loaded ads.

@override
void dispose() {
  _bannerKey.currentState?.dispose();
  super.dispose();
}

Hardware acceleration for video ads

In order for video ads to show successfully in your banner ad views, hardware acceleration must be enabled.

Hardware acceleration is enabled by default, but some apps may choose to disable it. If this applies to your app, we recommend enabling hardware acceleration for Activity classes that use ads.

If your app does not behave properly with hardware acceleration turned on globally, you can control it for individual activities as well. To enable or disable hardware acceleration, you can use the android:hardwareAccelerated attribute for the <application> and <activity> elements in your AndroidManifest.xml. The following example enables hardware acceleration for the entire app but disables it for one activity:

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

See the HW acceleration guide for more information about options for controlling hardware acceleration. Note that individual ad views cannot be enabled for hardware acceleration if the Activity is disabled, so the Activity itself must have hardware acceleration enabled.

---

🔗 Next Interstitial Ad