Banner Ads
This guide explains how to integrate banner ads into a Flutter app.
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.
Banner Ad management in Dart code is handled through the CASBanner class,
which extends the shared AdViewInstance class used for all ads displayed in a widgets.
The AdViewInstance class, inherits from the base AdInstance class, which is common for all CAS ad formats.
To display a AdViewInstance as a widget, you must instantiate an CASWidget for each ad instance.
CAS provides an option to enable autoReload to simplify your app logic. Before using the ad, you should decide whether to enable autoReload, or manually manage each ad loading cycle in your code.
When autoReload is enabled, a new ad will be automatically loaded after each display, and loading failures will trigger automatic retry attempts.
final bool isAutoReloadEnabled = true;
Manual load mode (autoReload: false ) is useful when you only need to show a single ad per app screen, and the screens change frequently.
Also, banner ads support automatic refreshInterval regardless of the autoReload setting.
Below is a diagram showing the ad lifecycle and how autoReload (isAutoload) and refreshInterval affects it.
Get the Ad size
To load a banner ad, you need to specify the ad size. To do this, choose one of the methods for obtaining an AdSize from the list below:
- Adaptive banner ads have a fixed aspect ratio for the maximum width. The adaptive size calculates the optimal height for that width with an aspect ratio similar to 320x50.
final double maxWidth = MediaQuery.of(context).size.width;
final AdSize adSize = AdSize.getAdaptiveBanner(maxWidth);
- Inline banner ads have a desired width and a maximum height, useful when you want to limit the banner's height. Inline banners are larger and taller compared to adaptive banners. They have variable height, including Medium Rectangle size, and can be as tall as the device screen.
final int width = MediaQuery.of(context).size.width.truncate();
final int maxHeight = 400;
final adSize = AdSize.getInlineBanner(width, maxHeight);
- Smart ad size selects the optimal dimensions depending on the device type. For mobile devices, it returns 320x50, while for tablets, it returns 728x90. In the UI, these banners occupy the same amount of space regardless of device type.
final adSize = AdSize.getSmartBanner(context);
- Medium Rectangle has a fixed size of 300x250.
final adSize = AdSize.mediumRectangle;
- Leaderboard has a fixed size of 728x90 and is allowed on tablets only.
final adSize = AdSize.leaderboard;
- Standard banner has a fixed size of 320x50 and is the minimum ad size.
final adSize = AdSize.banner;
Create Ad instance
The following example creates and loads an banner ad:
class BannerAdExampleState extends State<BannerAdExample> {
CASBanner? _bannerAd;
void _loadAd(AdSize adSize) {
// Disposing of the current ad if there is one.
_bannerAd?.dispose();
_bannerAd = CASBanner.createAndLoad(
size: adSize,
autoReload: isAutoReloadEnabled,
onAdLoaded: (AdViewInstance ad) {
// Called when an ad is successfully loaded.
print('$ad loaded');
},
onAdFailedToLoad: (AdInstance ad, AdError error) {
// Called when an ad load failed.
print('$ad failed to load: ${error.message}.');
},
);
}
}
Ad content may take some time to load after creating an ad instance.
To ensure the ad displays instantly when needed, create the ad instance in advance.
Use the onAdLoaded callback to be notified when the ad is ready for display.
When using an AdSize based on screen width, you should recalculate the size whenever
the device orientation changes and reload the banner ad to match the new layout.
late Orientation _currentOrientation;
@override
void didChangeDependencies() {
super.didChangeDependencies();
MediaQueryData mediaQuery = MediaQuery.of(context);
_currentOrientation = mediaQuery.orientation;
final double maxWidth = mediaQuery.size.width;
final AdSize adSize = ...;
_loadAd(adSize);
}
When using a fixed ad size, it's enough to load the ad instance once in initState().
@override
void initState() {
super.initState();
final AdSize adSize = ...;
_loadAd(adSize)
}
Ad refresh interval
The automatic refresh interval determines how often a new ad request is generated. Once the interval elapses, a new ad will automatically load and display. The interval countdown runs only while the ad is visible on screen. Set a custom refresh interval longer than 10 seconds, or 0 to disable refresh option. Default refresh interval is 30 seconds.
Override the automatic refresh interval in createAndLoad() arguments:
_bannerAd = CASBanner.createAndLoad(
size: adSize,
autoReload: isAutoReloadEnabled,
refreshInterval: 30,
);
Ad content callbacks
CASBanner has several optional callbacks for the ad lifecycle. These callbacks can be set either as arguments in the createAndLoad() function or later via the properties of the ad instance.
_bannerAd = CASBanner.createAndLoad(
size: adSize,
autoReload: isAutoReloadEnabled,
onAdLoaded: (AdViewInstance ad) {
// Called when an ad is successfully loaded.
print('$ad loaded');
},
onAdFailedToLoad: (AdInstance ad, AdError error) {
// Called when an ad load failed.
print('$ad failed to load: ${error.message}.');
},
onAdImpression: (AdInstance ad, AdContentInfo contentInfo) {
// Called when an impression occurs on the ad.
print('$ad impression');
},
onAdClicked: (AdInstance ad) {
// Called when a click is recorded for an ad.
print('$ad clicked');
},
);
Read more about AdContentInfo structure in Impression Level Data.
Show Ad Widget
CASWidget inherits from Flutter's Widget class and can be used like any other widget.
@override
Widget build(BuildContext context) {
return CASWidget(ad: _bannerAd!);
}
While the ad is loading, the widget will have a size of (1x1). When the ad loads, the widget will automatically adopt the selected size.
The size of the container in which you place your ad must be at least as large as the AdSize. Any padding effectively decreases the size of your container.
Release ad resource
Be sure to release ad resources if you’re no longer going to use the ad instance.
@override
void dispose() {
_bannerAd?.dispose();
super.dispose();
}
Manual reload Ad
When you want to manually control ad loading, use the load() function on the created ad instance to retry loading with the same configuration.
_bannerAd!.load();