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

Below is a diagram showing the ad lifecycle.

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.

int maxWidth = 360;
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.

int maxWidth = 360;
int maxHeight = 400;
AdSize adSize = AdSize.getInlineBanner(maxWidth, 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.

AdSize adSize = AdSize.getSmartBanner(context);

Medium Rectangle has a fixed size of 300x250.

AdSize adSize = AdSize.MEDIUM_RECTANGLE;

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

AdSize adSize = AdSize.LEADERBOARD;

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

AdSize adSize = AdSize.BANNER;

Create Ad View

The first step toward displaying a banner is to place CASBannerView in the layout for the Activity or Fragment in which you'd like to display it.

Create an CASBannerView using the ad size to add to your app's layout:

import com.cleversolutions.ads.android.CASBannerView;

class MyActivity extends Activity {
    CASBannerView bannerView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        bannerView = new CASBannerView(this, MyApplication.CAS_ID);
        bannerView.setSize(AdSize...);
        bannerView.setAutoloadEnabled(true);
        
        // Replace ad container with new ad view.
        adContainerView.removeAllViews();
        adContainerView.addView(bannerView, 
            new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
        );
    }

The easiest way to do this is to add one to the corresponding XML layout file. Here's an example that shows an activity's CASBannerView:

# main_activity.xml
...
  <com.cleversolutions.ads.android.CASBannerView 
      xmlns:ads="http://schemas.android.com/apk/res-auto"
      android:id="@+id/bannerView"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:gravity="center"
      ads:bannerSize="Standard320x50"/>
...

Note the following required attributes:
ads:bannerSize - Set the ad size you'd like to use.
See the banner size section below for details.

On create activity you should set CAS Id to the ad view:

import com.cleversolutions.ads.android.CASBannerView;

class MyActivity extends Activity {
    CASBannerView bannerView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        bannerView = (CASBannerView)findViewById(R.id.bannerView);
        bannerView.setCasId(MyApplication.CAS_ID);
        bannerView.setAutoloadEnabled(true);
    }

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:

bannerAd.adListener = object : AdViewListener {
    override fun onAdViewLoaded(view: CASBannerView) {
        // Invokes this callback when ad loaded and ready to present.
    }

    override fun onAdViewFailed(view: CASBannerView, error: AdError) {
        // Invokes this callback when an error occurred with the ad.
    }

    override fun onAdViewClicked(view: CASBannerView) {
        // Invokes this callback when a user clicks the ad.
    }

    override fun onAdViewPresented(view: CASBannerView, info: AdStatusHandler) {
        // Deprecated. Same as onAdImpression(AdContentInfo).
    }
}

bannerView.setAdListener(new AdViewListener() {
    @Override
    public void onAdViewLoaded(@NonNull CASBannerView view) {
      // Invokes this callback when ad loaded and ready to present.
    }

    @Override
    public void onAdViewFailed(@NonNull CASBannerView view, @NonNull AdError error) {
      // Invokes this callback when an error occurred with the ad.
    }

    @Override
    public void onAdViewClicked(@NonNull CASBannerView view) {
      // Invokes this callback when a user clicks the ad.
    }

    @Override
    public void onAdViewPresented(@NonNull CASBannerView view, @NonNull AdStatusHandler info) {
      // Deprecated. Same as onAdImpression(AdContentInfo).
    }
});

Load Ad

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

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

bannerView.setAutoloadEnabled(false);

By default enabled.

Handle Orientation Changes

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.

@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    bannerView.setSize(AdSize...);
    if (bannerView.isAutoloadEnabled == false) {
        bannerView.load();
    }
}

Ad view visibility

The banner is a normal view so you can feel free to change the visibility with the following method:

bannerView.setVisibility(View.GONE);

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:

bannerView.setRefreshInterval(interval);

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

To disable refresh ad use following method:

bannerView.disableAdRefresh();

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

Be sure to release ad resources if you’re no longer going to use the ad view.

override fun onDestroy() {
    super.onDestroy()
    bannerView?.destroy()
}

@Override
protected void onDestroy() {
  super.onDestroy();
  bannerView.destroy();
}

Check Ad availability

Use isLoaded() to check whether an ad is currently loaded.

if (bannerView.isLoaded()) {
}

Samples

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.

Get Started

Ad formats

Advanced topics