Banner Ads

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.

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.

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.

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.

const adSize = casai.Size.SMART;

4. Leaderboard has a fixed size of 728x90 and is allowed on tablets only.

const adSize = casai.Size.LEADERBOARD;

5. Standard Banner has a fixed size of 320x50 and is the minimum ad size

const adSize = casai.Size.BANNER;

Load the Ad

The following example creates and loads an banner ad:

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); 
  }); 

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); 
} 

function onAdLoaded(e) {
  if (e.detail.format === casai.Format.BANNER) {
    // Called when an ad is successfully loaded.
    console.log('Banner Ad loaded');
  }
}

function onAdLoadFailed(e) {
  if (e.detail.format === casai.Format.BANNER) {
    // Called when an ad load failed.
    console.log('Banner Ad failed to load:', e.detail.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.

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.

casai.bannerAd.load({
  adSize: adSize,
  maxWidth: 400,
  maxHeight: 350,
})

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:

casai.bannerAd.load({ 
  adSize: adSize, 
  refreshInterval: 30,
}) 

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.

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

Some anchor positions do not support offset on the X or Y axis, this can be seen in the table as (X, Y).

The coordinates on the screen are determined in Density-independent Pixels(DP).

casai.bannerAd.show({ 
  position: casai.Position.TOP_LEFT,
  offsetX: xOffsetInDP,
  offsetY: yOffsetInDP
});

Change the banner position on screen using the following method:

Hide the Ad

When you need to hide the banner ad from the user, call:

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.detail.format to determine the ad format.

function onAdClicked(e) {
  if (e.detail.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.

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
• Standard banner ad example