---
title: Banner Ads
description: This guide shows you how to integrate banner ads from CAS into an Android 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 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. <Image zoom src="/assets/Lifecycle-Banner-Ad.png" alt="Diagram" height="500" />

## 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:

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.

<CodeGroup synchronize={true}>
```kotlin
val maxWidth = 360
val adSize = AdSize.getAdaptiveBanner(maxWidth)
```

```java
int maxWidth = 360;
AdSize adSize = AdSize.getAdaptiveBanner(maxWidth);
```

</CodeGroup>

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.

<CodeGroup synchronize={true}>
```kotlin
val maxWidth = 360
val maxHeight = 400
val adSize = AdSize.getInlineBanner(maxWidth, maxHeight)
```

```java
int maxWidth = 360;
int maxHeight = 400;
AdSize adSize = AdSize.getInlineBanner(maxWidth, maxHeight);
```

</CodeGroup>

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

<CodeGroup synchronize={true}>
```kotlin
val adSize = AdSize.getSmartBanner(context)
```

```java
AdSize adSize = AdSize.getSmartBanner(context);
```

</CodeGroup>

4. **Medium Rectangle** has a fixed size of 300x250.

<CodeGroup synchronize={true}>
```kotlin
val adSize = AdSize.MEDIUM_RECTANGLE
```

```java
AdSize adSize = AdSize.MEDIUM_RECTANGLE;
```

</CodeGroup>

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

<CodeGroup synchronize={true}>
```kotlin
val adSize = AdSize.LEADERBOARD
```

```java
AdSize adSize = AdSize.LEADERBOARD;
```

</CodeGroup>

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

<CodeGroup synchronize={true}>
```kotlin
val adSize = AdSize.BANNER
```

```java
AdSize adSize = AdSize.BANNER;
```

</CodeGroup>

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

<Tabs>
<TabItem label="Programmatically" value="script">
Create an `CASBannerView` using the ad size to add to your app's layout:

<CodeGroup synchronize={true}>
```kotlin
import com.cleversolutions.ads.android.CASBannerView

class MyActivity : Activity() {
    private lateinit var bannerView: CASBannerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        bannerView = CASBannerView(this, MyApplication.CAS_ID)
        bannerView.size = adSize
        bannerView.isAutoloadEnabled = true

        // Replace ad container with new ad view.
        adContainerView.removeAllViews()
        adContainerView.addView(
            bannerView,
            LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
        )
    }
}
```

```java
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); // or any AdSize from above
        bannerView.setAutoloadEnabled(true);
        
        // Replace ad container with new ad view.
        adContainerView.removeAllViews();
        adContainerView.addView(
            bannerView, 
            new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
        );
    }
}
```

</CodeGroup>

</TabItem>

<TabItem label="XML Layout" value="xml">

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`:

```xml
# 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:

<CodeGroup synchronize={true}>
```kotlin
import com.cleversolutions.ads.android.CASBannerView

class MyActivity : Activity() {
    private lateinit var bannerView: CASBannerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        bannerView = findViewById(R.id.bannerView)
        bannerView.casId = MyApplication.CAS_ID
        bannerView.isAutoloadEnabled = true
    }
}
```

```java
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);
    }
}
```
</CodeGroup>

</TabItem>

<TabItem label="Compose" value="compose">

```kotlin
@Composable
fun BannerView(modifier: Modifier = Modifier) {
    val context = LocalContext.current
    val screenWidthDp = LocalConfiguration.current.screenWidthDp

    val bannerView = remember(screenWidthDp) {
        CASBannerView(context, MyApplication.CAS_ID).apply {
            // Adaptive banner based on current width.
            size = AdSize.getAdaptiveBanner(context, screenWidthDp) 
            isAutoloadEnabled = true

            // Add a listeners and other parameters to the banner view here.
            // adListener = ...
        }
    }

    AndroidView(
        modifier = modifier.wrapContentSize(),
        factory = { bannerView }
    )
}
```

</TabItem>
</Tabs>

## 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:

<CodeGroup synchronize="true">
```kotlin
bannerView.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).
    }
}

```

```java
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).
    }
});
```

</CodeGroup>

## Optional Placement name
An optional placement name for the ad instance that helps categorize and track statistics across different ad placements.

The placement name should be set before loading the ads. Maximum 100 characters allowed for the placement name.

<CodeGroup synchronize="true">
```kotlin
bannerView.placement = "BestPlace"
```

```java
bannerView.setPlacement("BestPlace")
```

</CodeGroup>

## 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 `CASBannerView`class.

<Tabs groupId="platform">
<TabItem label="Kotlin" value="kotlin">
```kotlin
bannerView.load()
```

</TabItem>
<TabItem label="Java" value="java">
```java
bannerView.load();
```

</TabItem>
<TabItem label="Compose" value="compose">
```kotlin
DisposableEffect(bannerView) {
    bannerView.load()
}
```

</TabItem>
</Tabs>

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

<CodeGroup synchronize="true">
```kotlin
bannerView.isAutoloadEnabled = false
```

```java
bannerView.setAutoloadEnabled(false);
```

</CodeGroup>

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.

<CodeGroup synchronize="true">
```kotlin
override fun onConfigurationChanged(newConfig: Configuration) {
    super.onConfigurationChanged(newConfig)
    bannerView.size = AdSize.getAdaptiveBanner(this, maxWidth)
    if (bannerView.isAutoloadEnabled == false) {
        bannerView.load()
    }
}
```

```java
@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    bannerView.setSize(AdSize.getAdaptiveBanner(this, maxWidth)); 
    if (bannerView.isAutoloadEnabled() == false) {
        bannerView.load();
    }
}
```

</CodeGroup>

## Ad view visibility

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

<CodeGroup synchronize="true">
```kotlin
bannerView.visibility = View.GONE
```

```java
bannerView.setVisibility(View.GONE);
```

</CodeGroup>

## 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:

<CodeGroup synchronize="true">
```kotlin
bannerView.refreshInterval = interval
```

```java
bannerView.setRefreshInterval(interval);
```

</CodeGroup>

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

To disable refresh ad use following method:

<CodeGroup synchronize="true">
```kotlin
bannerView.disableAdRefresh()
```

```java
bannerView.disableAdRefresh();
```

</CodeGroup>

<Info>
- The automatic refresh occurs only if the banner is visible on screen.  
- The `isAutoloadEnabled` has no effect on refreshing the banner ad.
</Info>

## Release ad resource

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

<Tabs groupId="platform">
<TabItem label="Kotlin" value="kotlin">
```kotlin
override fun onDestroy() {
    super.onDestroy()
    bannerView.destroy()
}
```

</TabItem>
<TabItem label="Java" value="java">
```java
@Override
protected void onDestroy() {
  super.onDestroy();
  bannerView.destroy();
}
```

</TabItem>
<TabItem label="Compose" value="compose">
```kotlin
DisposableEffect(bannerView) {
    onDispose { bannerView.destroy() }
}
```

</TabItem>
</Tabs>

## Check Ad availability

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

<CodeGroup synchronize="true">
```kotlin
if (bannerView.isLoaded) {
}
```

```java
if (bannerView.isLoaded()) {
}
```

</CodeGroup>

## Samples
- Kotlin samples
  - [Banner Ad Activity](https://github.com/cleveradssolutions/CAS-Android/blob/master/kotlinSample/src/main/java/com/cleveradssolutions/sampleapp/banner/programmatic/BannerAdActivity.kt)
  - [Adaptive Banner Ad Activity](https://github.com/cleveradssolutions/CAS-Android/blob/master/kotlinSample/src/main/java/com/cleveradssolutions/sampleapp/banner/xml/AdaptiveBannerAdActivity.kt)
- Java samples
  - [Banner Ad Activity](https://github.com/cleveradssolutions/CAS-Android/blob/master/javaSample/src/main/java/com/cleveradssolutions/sampleapp/banner/programmatic/BannerAdActivity.java)
  - [Adaptive Banner Ad Activity](https://github.com/cleveradssolutions/CAS-Android/blob/master/javaSample/src/main/java/com/cleveradssolutions/sampleapp/banner/xml/AdaptiveBannerAdActivity.java)
- Jetpack Compose samples
  - [Banner Screen](https://github.com/cleveradssolutions/CAS-Android/blob/master/composeSample/src/main/java/com/cleveradssolutions/sampleapp/formats/BannerScreen.kt)
  - [Lazy Banner Screen](https://github.com/cleveradssolutions/CAS-Android/blob/master/composeSample/src/main/java/com/cleveradssolutions/sampleapp/formats/LazyBannerScreen.kt)

## Hardware acceleration for video ads

In order for video ads to show successfully in your banner ad views, [hardware acceleration](https://developer.android.com/guide/topics/graphics/hardware-accel) 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](https://developer.android.com/guide/topics/manifest/application-element) and [activity](https://developer.android.com/guide/topics/manifest/activity-element) elements in your **AndroidManifest.xml**. The following example enables hardware acceleration for the entire app but disables it for one activity:

```xml
<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](https://developer.android.com/guide/topics/graphics/hardware-accel) 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.