# Android > Integration guides > Banner

Source: https://help-display-sdk.equativ.com/android/integration/banner.html

This page explains how to use the **Equativ Display SDK** to display a banner ad in your application.

---

## Overview

Banner ads are loaded and displayed by [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) instances.

To load and display a banner ad, you will need:
- A fully configured **Equativ Display SDK**.
- An instance of [`SASAdPlacement`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html) that will be used to perform ad calls to the delivery engine.
- An instance of [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) that will load and show the banner ad.
- An object implementing the [`SASBannerView.BannerListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/index.html) listener interface to monitor banner ad lifecycle events.

The next sections describe in details how to create and load a banner ad.

You can also refer to the [samples](https://github.com/smartadserver/equativ-display-sdk-samples-android) if you want to copy/paste the whole integration.

## Configuring the SDK
The **Equativ Display SDK** needs to be configured before making any ad calls. You will have to call the method [`configure()`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/configure.html) of the [`SASConfiguration`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/index.html) shared instance to do so.

This method must be called once, as soon as possible.

Ideally call it in the `onCreate()` method of your `Application` class. For instance:

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Configure Equativ Display SDK
        SASConfiguration.configure(this)
    }
}
```

Any ad call performed before calling the [`configure()`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.util/-s-a-s-configuration/configure.html) method will fail by throwing an `IllegalStateException`.

## Creating a placement
You will need an _ad placement_ to perform an ad call. A placement identifies a part of your inventory where you want to display ads.

Creating an ad placement is done by instantiating a [`SASAdPlacement`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html) object using mandatory parameters _site ID_, _page ID_, _format ID_ and an optional _keyword targeting_ String (more info [in the API documentation](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html)).

```kotlin
val adPlacement = SASAdPlacement(SITE_ID, PAGE_ID, FORMAT_ID, OPTIONAL_KEYWORD_TARGETING)
```

> You can add several information to your _ad placements_ in order to **increase the monetization**.
>
> For instance you can provide a [_Seller Defined Audience_](https://help-display-sdk.equativ.com/sellerdefinedaudience.html.md) object, or a [_Supply Chain Object_](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/supply-chain-object-string.html) if your are an inventory reseller.

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type.
You will find more information on the dedicated section [here](https://help-display-sdk.equativ.com/android/troubleshooting.html#test).

Don't forget to remove all test placements before releasing your app!

## Creating a banner view

A banner ad is displayed by an instance of the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) class.

Since this class is a subclass of the Android `View` class, there are two ways of instantiating it:
- In an XML layout file where your banner should be displayed (most straightforward):
    ```xml
    <com.equativ.displaysdk.ad.banner.SASBannerView
        android:id="@+id/banner"
        android:layout_width="match_parent"
        android:layout_height="50dp" />
    ```

    You can then assign it to a variable like any other Views you are handling in your app.

    > The [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) component __does not__ support the `wrap_content` value for either its width or height except for the specific native ad display case described in the resizing section mentioned below.
    > You must either use `match_parent` (usually for its width) or use a numeric value like 50dp above (as device independent pixels).
    > Please refer to the [How to adapt the banner size after loading](https://help-display-sdk.equativ.com/android/integration/banner.html#how-to-adapt-the-banner-size-after-loading) section to handle the dynamic resing of the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) according to the ads received.

- By code directly:
    ```kotlin
val bannerView = SASBannerView(context)
    ```

Note that when instantiating a [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) by code, it does not belong to any `View` hierarchy, it is
up to you to add it to your view hierarchy with appropriate Android `LayoutParams` as you would for any other Android `View`.

## Loading an ad

Once the banner view is properly instantiated, an ad can be loaded using the _ad placement_ created earlier.

```kotlin
bannerView.loadAd(adPlacement)
```

The banner creative will be automatically displayed when loaded.

> To propose a smooth integration to your users and avoid displaying an empty space in case there is no ad to show,
> it is advised to hide the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) instance until an ad is successfully loaded.
>
> To do that, you must listen to ad loading events, as described in the next section.

## Listening to ad loading events

You can listen to ad loading events (as well as other banner view related events) by setting an object implementing
the [`SASBannerView.BannerListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/index.html) interface on the banner view.

```kotlin
bannerView.bannerListener = object : SASBannerView.BannerListener {
    override fun onBannerAdLoaded(adInfo: SASAdInfo) {
        Log.i("Sample", "Banner loading completed")
    }
    override fun onBannerAdFailedToLoad(exception: SASException) {
        Log.i("Sample", "Banner loading failed: $exception")
    }
    override fun onBannerAdClicked() {
        Log.i("Sample", "Banner was clicked")
    }
}
```

You can use the [`onBannerAdLoaded`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/on-banner-ad-loaded.html) and [`onBannerAdFailedToLoad`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/on-banner-ad-failed-to-load.html) methods to show or hide the banner respectively,
try to reload an in case of failure, and so on. You will find a list of all the available methods [in the API documentation](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/index.html).

The [`loadAd`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/load-ad.html) method of the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) executes the ad loading task asynchronously in a different thread
from the calling thread. Therefore, if the [`loadAd`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/load-ad.html) method is called while a previous ad call is being performed and has not finished yet,
it will fail with a [`SASException`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.exception/-s-a-s-exception/index.html) of type `PENDING_AD_LOADING` in the [`onBannerAdFailedToLoad`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/on-banner-ad-failed-to-load.html) method of the [`SASBannerView.BannerListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/index.html), if any set.

## Listening to ad audio events

You can listen to ad audio events (as well as other banner view events) by implementing the [`SASBannerView.BannerListener`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/index.html) interface on the banner view.

```kotlin
bannerView.bannerListener = object : SASBannerView.BannerListener {
    override fun onBannerAdAudioStart() {
        Log.i(TAG, "Banner video ad will start to play audio")

        // Equativ Display SDK is notifying your app that it will play audio.
        // You could optionally pause music depending on your apps design.
    }

    override fun onBannerAdAudioStop() {
        Log.i(TAG, "Banner video ad did stop to play audio")

        // Equativ Display SDK is notifying your app that it has stopped playing audio.
        // Depending on your apps design, you could resume music here.
    }
}
```

> All video ads start muted and require user interaction to toggle audio.

## How to adapt the banner size after loading

Although the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) instance takes care of resizing the creative to make it fit properly while preserving its ratio,
you can go further and resize the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html)'s height to match the creative's width/height ratio, hence eliminating empty spaces around the creative.

This is often the case when your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) needs to deliver 300x50, 300x250 formats or even 16/9 video, etc.

Use the [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) parameter of the [`SASAdInfo`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/index.html) instance you received via the [`onBannerAdLoaded`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/on-banner-ad-loaded.html) listener method.
This [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) property can have several values:
- a positive `Double`: The actual aspectRatio of the loaded creative.
- `-1`: The best fit for your ad is to use the `LayoutParams.WRAP_CONTENT` value for the height of your your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html).
- `null`: The SDK does not have any information about the aspectRatio of the ad. We advise you to set a default hardcoded height to your ad.

Then it is up to you to compute the perfect height for your banner based on this ratio.

  > As mentioned in the [Creating a banner view](https://help-display-sdk.equativ.com/android/integration/banner.html#creating-a-banner-view-create) section above, the `LayoutParams.WRAP_CONTENT` value should be used for your your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) only when the received [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) value is `-1`, which happens only when the received ad is a native ad.
  > For all other formats, using the `LayoutParams.WRAP_CONTENT` height will lead to unpredictable [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) size results.

The best place to add the resizing code is in your [`onBannerAdLoaded`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/-banner-listener/on-banner-ad-loaded.html) implementation. Here is an example:

```kotlin
override fun onBannerAdLoaded(adInfo: SASAdInfo) {
    // Implementation example
    // Here the computed height is based on the width of the device and the received aspectRatio (if any).
    adInfo.aspectRatio?.let { aspectRatio ->
        val layoutParams = bannerView.layoutParams

        layoutParams.height = if (aspectRatio < 0) {
            LayoutParams.WRAP_CONTENT
        } else {
            (context.resources.displayMetrics.widthPixels / aspectRatio).toInt()
        }

        bannerView.layoutParams = layoutParams
    }
}
```

### Good practices

The usage of [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) is intended to work with responsive creatives. If your creative is not responsive, rendering issues may occur (huge blank space or cropped creative for instance). Here are some good practices in case you are handling non responsive creatives:

**If your creative is non-responsive and smaller than its reserved ad placement**

We suggest defining a hardcoded [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) size based on the given [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html). For instance, if your [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) is `6.4` (320/50), it refers to a 320x50 format, so you can hardcode your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) size to 320px width and 50px height. You can
do the same if your [`aspectRatio`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-info/aspect-ratio.html) is `1.2` (300/250), referring to 350x250 format.

Once you have your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) with hardcoded size, you will be able to center it within the view reserved for your ad.

**If your creative is non-responsive and bigger than its reserved ad placement**

Unfortunately, in that case, the resulting ad will be cropped regardless, as the initial image is bigger than the reserved spot.

## Disposing of a banner view

Once you are done using a banner view, typically when its hosting `Activity` is being destroyed, you must call
the [`onDestroy`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/on-destroy.html) method of the [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) to release the resources it was using.

```kotlin
/**
* Overriden from Activity class
*/
override fun onDestroy() {
    super.onDestroy();
    bannerView.bannerListener = null
    bannerView.onDestroy()
}
```

## Improving parallax ad rendering

The _banner view_ can be used to display _parallax ads_. A parallax ad is an inline ad which shows part of a full screen ad under the app content during scroll interactions. It supports images, agency scripts and HTML 5 creatives.

The [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) can automatically display this type of ads when integrated into any scrollable view.

The creative displayed inside the parallax banner view will takes the whole screen by default (minus the navigation bar and the status bar). It means that part of the creative might be hidden by some elements of your UI, especially elements covering the scrollable view.

You can prevent part of the ad to be hidden by the UI by defining _custom parallax margins_ on your [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html) instance by providing a [`SASParallaxMargins`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-parallax-margins/index.html) instance to the [`parallaxMargins`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/parallax-margins.html) property:

    bannerView.parallaxMargins = SASParallaxMargins(left = 10, top = 50, right = 10, bottom = 20)


## Native ad in banner

Starting with **Equativ Display SDK** __v8.3.0__ it is possible to display native ad through [`SASBannerView`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/index.html). You have nothing more to do than calling [`loadAd`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.ad.banner/-s-a-s-banner-view/load-ad.html) with a native ad [`SASAdPlacement`](https://help-display-sdk.equativ.com/android/API/-display%20-s-d-k/com.equativ.displaysdk.model/-s-a-s-ad-placement/index.html). You can use the native ad [test placements](https://help-display-sdk.equativ.com/android/troubleshooting.html#test) to try it by yourself.

If you want to integrate native ad by using the more advanced integration, please check the [native ad integration article](https://help-display-sdk.equativ.com/android/integration/native-ad.html.md).

## Video Header Ad - A specific way to implement your video banner

The _banner view_ can be used as a __video header ad__ format, following a specific integration in your application. To help you doing so, we have created integration samples and external classes to
add to your app to integrate this new __video header ad__ format as easily as possible. You'll find more information in the [dedicated article](https://help-display-sdk.equativ.com/creatives/video-header-ad.html.md).