# Banner

Banner ads are rectangular image or text ads that occupy a space inside the application layout. They stay on screen while the users interact with the app and can automatically refresh after a certain period of time. If you are new in mobile advertising, they are an excellent choice to start.

## **Integration**

There are two ways to integrate a banner: using code or adding the banner view inside a layout. Below we show some examples for both methods:

### Layout XML

```markup
<com.wortise.ads.banner.BannerAd
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:adSize="HEIGHT_50"
    app:adUnitId="Wortise Ad Unit ID" />
```

The widget has support for the following parameters:

| Parameter               | Type    | Required | Description                                                                                                     |
| ----------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| **app:adUnitId**        | String  | **Yes**  | The ad unit ID to assign to the banner                                                                          |
| **app:adSize**          | AdSize  | No       | Maximum size (height) for the banner. The possible values for this parameter are declared in the `AdSize` class |
| **app:autoRefreshTime** | Integer | No       | Value in seconds that represents the time that must elapse to load a new banner ad                              |

### **Code**

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
class MainActivity : Activity() {

    private var bannerAd: BannerAd? = null
    
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        bannerAd = BannerAd(this).also {
	        it.adSize = AdSize.HEIGHT_50
	        it.adUnitId = "<Ad Unit ID de Wortise>"
	        
	        // For example, we add the BannerAd into a FrameLayout
	        val frameLayout = findViewById<FrameLayout>(R.id.frame)
	        frameLayout.addView(it)
	        
	        it.loadAd()
        }
    }
    
    override fun onDestroy() {
        ...
        bannerAd?.destroy()
    }
    
    override fun onPause() {
        ...
        bannerAd?.pause()
    }
    
    override fun onResume() {
        ...
        bannerAd?.resume()
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
public class MainActivity extends Activity {

    private BannerAd mBannerAd;
    
    @Override
    public void onCreate(Bundle savedInstanceState) {
        ...
        mBannerAd = new BannerAd(this);
        mBannerAd.setAdSize(AdSize.HEIGHT_50);
        mBannerAd.setAdUnitId("Wortise Ad Unit ID");
        
        // For example, we add the BannerAd into a FrameLayout
        FrameLayout frameLayout = findViewById(R.id.frame);
        frameLayout.addView(mAdView);

        mBannerAd.loadAd();
    }
    
    @Override
    public void onDestroy() {
        ...
        mBannerAd.destroy();
    }
    
    @Override
    public void onPause() {
        ...
        mBannerAd.pause();
    }
    
    @Override
    public void onResume() {
        ...
        mBannerAd.resume();
    }
}
```

{% endtab %}
{% endtabs %}

The `BannerAd` class providers the following methods to configure the instance:

| Method                               | Required | Descripción                                                                                                     |
| ------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `setAdUnitId(String)`                | **Yes**  | Assigns an ad unit to the banner                                                                                |
| `setAdSize(AdSize)`                  | No       | Maximum size (height) for the banner. The possible values for this parameter are declared in the `AdSize` class |
| `setAutoRefreshTime(long)`           | No       | Value in milliseconds that represents the time that must elapse to load a new banner ad                         |
| `setAutoRefreshTime(long, TimeUnit)` | No       | Same as previous method, but allows to specify the time unit of the passed value                                |

## **Adaptive banners**

Adaptive banners are a new banner format where the size of the ads is adapted according to the device and the app user-interface, in order to maximize performance.

Currently there is support for two kind of adaptive banners:

### Anchored

This kind of banner is designed to replace the traditional 320x50 banners and be positioned at the top or bottom of the screen.

To make use of this format, the following code must be used to configure an adaptive size:&#x20;

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// It is needed to specify the banner width
val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width)
bannerAd.adSize = adSize
```

{% endtab %}

{% tab title="Java" %}

```java
// It is needed to specify the banner width
AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width);
mBannerAd.setAdSize(adSize);
```

{% endtab %}
{% endtabs %}

Alternatively, this other option can be implemented to let the SDK calculate the banner width, where the `BannerAd` instance itself or the `View` that will contain it should be passed:

{% hint style="warning" %}
In this option, it is **highly recommended** that the `View` passed to the method is already added to the app’s layout, so that the SDK can correctly calculate all the dimensions.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view)
bannerAd.adSize = adSize
```

{% endtab %}

{% tab title="Java" %}

```java
AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view);
mBannerAd.setAdSize(adSize);
```

{% endtab %}
{% endtabs %}

### Inline

This other kind of banner, in comparison to the anchored, is designed to have a variable height and be positioned inside a scrolling content.

In this case, the following code must be used to configure a proper adaptive size:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val maxHeight = 200

// It is needed to specify the banner width. The maximum height is an
// optional parameter
val adSize = AdSize.getInlineAdaptiveBannerAdSize(context, width, maxHeight)
bannerAd.adSize = adSize
```

{% endtab %}

{% tab title="Java" %}

```java
int maxHeight = 200;

// It is needed to specify the banner width. The maximum height is an
// optional parameter
AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(
    context, width, maxHeight
);
mBannerAd.setAdSize(adSize);
```

{% endtab %}
{% endtabs %}

Alternatively, this other option can be implemented to let the SDK calculate the banner width, where the `BannerAd` instance itself or the `View` that will contain it should be passed:

{% hint style="warning" %}
In this option, it is **highly recommended** that the `View` passed to the method is already added to the app’s layout, so that the SDK can correctly calculate all the dimensions.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val maxHeight = 200

val adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight)
bannerAd.adSize = adSize
```

{% endtab %}

{% tab title="Java" %}

```java
int maxHeight = 200;

AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight);
mBannerAd.setAdSize(adSize);
```

{% endtab %}
{% endtabs %}

## **Listener setup**

A listener can be set to any `BannerAd` instance to receive the events that happen during its lifecycle. For this, it is needed to implement the `BannerAd.Listener` interface as shown in the example below:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
bannerAd.listener = object : BannerAd.Listener() {

    override fun onBannerClicked(ad: BannerAd) {
        // Invoked when the ad has been clicked
    }

    override fun onBannerFailedToLoad(ad: BannerAd, error: AdError) {
        // Invoked when the ad could not be loaded
        // (because of an error or no fill)
    }
    
    override fun onBannerImpression(ad: BannerAd) {
        // Invoked when the ad has generated an impression
    }

    override fun onBannerLoaded(ad: BannerAd) {
        // Invoked when the ad has been loaded
    }
    
    override fun onBannerRevenuePaid(ad: BannerAd,
                                     data: RevenueData) {
        // Invoked when the ad has generated revenue
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
mBannerAd.setListener(new BannerAd.Listener() {
    @Override
    public void onBannerClicked(@NonNull BannerAd ad) {
        // Invoked when the ad has been clicked
    }
    
    @Override
    public void onBannerFailedToLoad(@NonNull BannerAd ad,
                                     @NonNull AdError error) {
        // Invoked when the ad could not be loaded
        // (because of an error or no fill)
    }
    
    @Override
    public void onBannerImpression(@NonNull BannerAd ad) {
        // Invoked when the ad has generated an impression
    }

    @Override
    public void onBannerLoaded(@NonNull BannerAd ad) {
        // Invoked when the ad has been loaded
    }
    
    @Override
    public void onBannerRevenuePaid(@NonNull BannerAd ad,
                                     @NonNull RevenueData data) {
        // Invoked when the ad has generated revenue
    }
});
```

{% endtab %}
{% endtabs %}