--- title: Banner Ads description: This guide explains how to integrate banner ads into a Cordova 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 Cordova code is handled through the `casai.bannerAd` object. CAS provides an option to enable `autoReload` to simplify your app logic. The `autoReload` is enabled by default, loading failures will trigger automatic retry attempts. You should decide whether to enable `autoReload`, or manually manage each ad loading cycle in your code. Also, banner ads support automatic `refreshInterval` regardless of the `autoReload` setting. Below is a diagram showing the ad lifecycle and how `autoReload` and `refreshInterval` affect it. Diagram ## Get the Ad size To load a banner ad, you need to specify the ad size. To do this, choose one of the `casai.Size` equivalents provided by the Cordova plugin: 1. **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. By default, the full screen width will be used. You can limit width by specifying a `maxWidth` in the parameters. ```js const adSize = casai.Size.ADAPTIVE; ``` 2. **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. Specify the `maxWidth` and `maxHeight` dimensions to limit the ad size. ```js const adSize = casai.Size.INLINE; ``` 3. **Smart** 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. ```js const adSize = casai.Size.SMART; ``` 4. **Leaderboard** has a fixed size of 728x90 and is allowed on tablets only. ```js const adSize = casai.Size.LEADERBOARD; ``` 5. **Standard Banner** has a fixed size of 320x50 and is the minimum ad size ```js const adSize = casai.Size.BANNER; ``` ## Load the Ad The following example creates and loads an banner ad: ```js casai.bannerAd.load({ adSize: adSize, autoReload: true, }) .then(() => { // Called when an ad is successfully loaded. console.log('Banner Ad loaded'); }) .catch((error) => { // Called when an ad load failed. console.error('Banner Ad failed to load:', error.message); }); ``` ```js try { await casai.bannerAd.load({ adSize: adSize, autoReload: true, }); // Called when an ad is successfully loaded. console.log('Banner Ad loaded'); } catch (error) { // Called when an ad load failed. console.error('Banner Ad failed to load:', error.message); } ``` ```js function onAdLoaded(event){ if (event.format === casai.Format.BANNER) { // Called when an ad is successfully loaded. console.log('Banner Ad loaded'); } } function onAdLoadFailed(event){ if (event.format === casai.Format.BANNER) { // Called when an ad load failed. console.log('Banner Ad failed to load:', event.message); } } document.addEventListener('casai_ad_loaded', onAdLoaded); document.addEventListener('casai_ad_load_failed', onAdLoadFailed); casai.bannerAd.load({ adSize: adSize, autoReload: true, }); function unsubscribeInterstitialLoadEvents() { document.removeEventListener('casai_ad_loaded', onAdLoaded); document.removeEventListener('casai_ad_load_failed', onAdLoadFailed); } ``` Ad content may take some time to load after creating an ad instance. To ensure the ad displays instantly when needed, load the ad instance in advance. Use the `casai_ad_loaded` event or `Promise` to be notified when the ad is ready for display. - Read more about `AdContentInfo` structure in [Impression Level Data](Cordova/Impression-Level-Data). - Read more about [AdError](Cordova/Ad-errors) structure. ## Limit the ad size When using an AdSize based on screen width or height, you can restrict the ad size by specifying the `maxWidth` and `maxHeight` properties. ```js casai.bannerAd.load({ adSize: adSize, maxWidth: 400, // [!code highlight] maxHeight: 350, // [!code highlight] }) ``` Maximum width for `ADAPTIVE` and `INLINE` banners in Density-independent Pixels(DP). By default, adaptive and inline banners use the full device width. Automatically clamped to the screen bounds and updated on orientation changes. --- Maximum height for `INLINE` banners in Density-independent Pixels(DP). By default, inline adaptive banners use the device height. Automatically clamped to the screen bounds and updated on orientation changes. ## 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 `refreshInterval` property: ```js casai.bannerAd.load({ adSize: adSize, refreshInterval: 30, // [!code highlight] }) ``` ## Display the Ad The banner will not be visible until `show()` is called. The show function has a position parameter that specifies where the banner ad should be placed. The `casai.Position` lists the valid ad position values. By default, the banner ad is centered at the bottom. ```js casai.bannerAd.show({ position: casai.Position.BOTTOM_CENTER, }); ``` To change the banner’s position on the screen, simply call the show function again with the new parameters. The banner's activity can be changed even if it is not ready to be shown yet. When the ad becomes ready, it will be shown automatically if autoload/show logic requires it. ## The Ad coordinates on the screen The offsetX and offsetY properties allow you to adjust the banner’s position relative to the specified anchor position, in DP. Our SDK will not allow an ad to be placed outside the screen or overlap with screen cutouts. Some anchor positions do not support offset on the X or Y axis, this can be seen in the table as (X, Y). | | Left | Center | Right | | ------ | -------- | :----: | -------: | | Top | TL(X, Y) | TC(Y) | TR(X, Y) | | Middle | ML(X) | MC(-) | MR(X) | | Bottom | BL(X, Y) | BC(Y) | BR(X, Y) | The coordinates on the screen are determined in Density-independent Pixels(DP). ```js casai.bannerAd.show({ position: casai.Position.TOP_LEFT, offsetX: xOffsetInDP, offsetY: yOffsetInDP }); ``` ## Hide the Ad When you need to hide the banner ad from the user, call: ```js casai.bannerAd.hide(); ``` ## Listening for the Ad Clicked The plugin allows you to listen for the `casai_ad_clicked` event, which is triggered whenever a user clicks an ad. This can be useful for analytics, custom tracking, or UI reactions. You can check `e.format` to determine the ad format. ```js function onAdClicked(event){ if (event.format === casai.Format.BANNER) { // Called when a click is recorded for an banner ad. } } document.addEventListener('casai_ad_clicked', onAdClicked); ``` ## Release Ad resource Destroys the ad content and releases any associated resources when the ad is no longer needed to clean up resources and prevent memory leaks. ```js casai.bannerAd.destroy(); ``` Call `load()` again to create and load a new ad instance and restore autoload behavior if needed. ## Complete example - [Adaptive banner ad example](https://github.com/cleveradssolutions/CAS-Cordova/blob/main/example/www/js/AdaptiveBannerExample.js) - [Standard banner ad example](https://github.com/cleveradssolutions/CAS-Cordova/blob/main/example/www/js/BannerExample.js)