# Banner/MREC Ads

## What are Banner/MREC Ads?

Banner or Medium Rectangle (MREC) Ad Units display a rectangular creative within an app. They occupy a portion of the app layout and stay on the screen as the users interact with the app. Refer to the [Ad Size](#a-d-size) section for a list of supported ad sizes for Banner/MREC Ad Units.

## What are Audio Banner Ads?

Audio Banner Ad Units display a rectangular creative with an accompanying audio component within an app. HyprMX provides an optional interface to receive callbacks notifying your application of interruptions to the Audio Stream by an Audio Banner Ad and when the Ad audio is finished to clear the interruption. All sizes supported for Banner/MREC Ads are supported in Audio Banner Ads.

#### Refresh Requirements <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

An Audio Banner Ad must remain on screen for the duration of the audio playback. To ensure the banner placement is not refreshed until the audio is complete, please set the refresh interval in your mediator's dashboard to 30 seconds or greater.

## How to Display Banner Ads

### Integrate & Initialize HyprMX <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

Before you start, make sure you have correctly integrated and initialized the HyprMX SDK. To integrate and initialize HyprMX, see our [Setup Guide](https://documentation.hyprmx.com/sdk-integration-guides/android-amazon).

### Initialize a BannerView <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

BannerViews are initialized with their [placement name](#placement-name) and [ad size](#a-d-size). &#x20;

#### **Placement Name**

HyprMX utilizes placements to load and display an ad. Placements are used to represent a point in your application's workflow where you'd like to show an ad, and placement names are a string that identifies individual banner placements in your application.&#x20;

{% hint style="info" %}
If you don't have your placement information, please reach out to your account manager to configure your banner placements. In return, they will provide the names of the new placements.
{% endhint %}

#### **Ad Size**

Banners are initialized using one of the pre-defined ad sizes.

| **Constant**                | **Size** |
| --------------------------- | -------- |
| HyprMXAdSizeShort           | 300x50   |
| HyprMXAdSizeBanner          | 320x50   |
| HyprMXAdSizeMediumRectangle | 300x250  |
| HyprMXAdSizeLeaderboard     | 728x90   |
| HyprMXAdSizeSkyScraper      | 160x600  |

To initialize your banner view, you can use XML, code integration, or a combination of the two.&#x20;

**Code Initialization**

When constructing a new banner view, the activity context must be used.

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

```java
HyprMXBannerView bannerView = new HyprMXBannerView(activityContext, null, "placement", HyprMXBannerSize.HyprMXAdSizeBanner.INSTANCE);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val bannerView = HyprMXBannerView(context = activityContext, placementName = "placementName", adSize = HyprMXBannerSize.HyprMXAdSizeBanner)
```

{% endtab %}
{% endtabs %}

**XML Initialization**

The banner view can be initialized in XML as seen below, with the attributes `app:hyprMXAdSize` and `app:hyprMXPlacementName`.

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

```xml
<com.hyprmx.android.sdk.banner.HyprMXBannerView
  android:id="@+id/bannerView"
  android:layout_width="320dp"
  android:layout_height="50dp"
  android:layout_margin="16dp"
  app:hyprMXAdSize="HyprMXAdSizeBanner"
  app:hyprMXPlacementName="placementName" />
```

{% endtab %}
{% endtabs %}

**Code Setting of Name/Size**

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

```java
bannerView.setPlacementName("placementName");
bannerView.setAdSize(HyprMXBannerSize.HyprMXAdSizeBanner.INSTANCE);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
bannerView.placementName = "placementName"
bannerView.adSize = HyprMXBannerSize.HyprMXAdSizeBanner
```

{% endtab %}
{% endtabs %}

### Adding Banners to your View <a href="#bannerads6.0.0-add_viewaddingbannerstoyourview" id="bannerads6.0.0-add_viewaddingbannerstoyourview"></a>

Add your BannerView to your View using XML or code and configure its layout to match your requested ad size.&#x20;

**Example Using XML:**

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

```xml
<com.hyprmx.android.sdk.banner.HyprMXBannerView
  android:id="@+id/bannerView"
  android:layout_width="320dp"
  android:layout_height="50dp"
  android:layout_margin="16dp"
  app:hyprMXAdSize="HyprMXAdSizeBanner"
  app:hyprMXPlacementName="placementName" />
```

{% endtab %}
{% endtabs %}

**Example using Code:**

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

```java
LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(320, 50);
params.gravity = Gravity.CENTER_HORIZONTAL;
bannerView.setLayoutParams(params);
linearLayout.addView(bannerView);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val linearLayout:LinearLayout = findViewById(R.id.example_linear_layout)
bannerView.apply {
  val params = LinearLayout.LayoutParams(320, 50)
  params.gravity = Gravity.CENTER_HORIZONTAL
  layoutParams = params
}
linearLayout.addView(bannerView)
```

{% endtab %}
{% endtabs %}

### Loading Advertisements <a href="#bannerads6.0.0-loading_adsloadingadvertisements" id="bannerads6.0.0-loading_adsloadingadvertisements"></a>

**To load a banner ad:**

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

```java
bannerView.loadAd(new HyprMXLoadAdListener() {
  @Override
  public void onAdLoaded(boolean isAdAvailable) {
    // Do something
  }
});
```

{% endtab %}

{% tab title="Java (Lambda)" %}

```java
bannerView.loadAd(isAdAvailable -> {
    // Do something
});
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
bannerView.loadAd { isAdAvailable ->
   // Do something
}
```

{% endtab %}

{% tab title="Kotlin (Coroutines)" %}

```kotlin
val isAdAvailable = bannerView.loadAd()

// Do something
```

{% endtab %}
{% endtabs %}

Your bannerView will load an ad and render it in its view. To receive ad load success and other lifecycle callbacks, implement the `HyprMXBannerListener` and set the listener on your bannerView.

### Setting a HyprMXBannerListener (Optional) <a href="#bannerads6.0.0-delegatesettingahyprmxbannerdelegate-optional" id="bannerads6.0.0-delegatesettingahyprmxbannerdelegate-optional"></a>

To receive lifecycle callbacks on your `HyprMXBannerView`, implement the `HyprMXBannerListener`.&#x20;

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

```java
bannerView.setListener(listener);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
bannerView.listener = listener
```

{% endtab %}
{% endtabs %}

**Implement the HyprMXBannerListener:**

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

```java
/**
 * A click event has occurred on the banner
 *
 * @param ad The HyprMXBannerView that had the click event
 */
@Override
public void onAdClicked(@NotNull HyprMXBannerView view) {}

/**
 * The click event on the banner has transition to an overlay
 *
 * @param ad The HyprMXBannerView that had the click event
 */
@Override
public void onAdOpened(@NotNull HyprMXBannerView view) {}

/**
 * The opened overlay has been dismissed
 *
 * @param ad The HyprMXBannerView that triggered the overlay
 */
@Override
public void onAdClosed(@NotNull HyprMXBannerView view) {}

/**
 * The click event on the banner will open a third party application to
 * process the click
 *
 * @param ad The HyprMXBannerView that had the click event
 *
 * @deprecated it will be removed on a major future release
 */
@Override
public void onAdLeftApplication(@NotNull HyprMXBannerView view) {}

/**
 * The impression event on the banner when the banner is considered visible and impressed.
 *
 * @param ad The HyprMXBannerView that had the impression event
 */
@Override
public void onAdImpression(@NonNull HyprMXBannerView view) {}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
/**
 * A click event has occurred on the banner
 *
 * @param ad The HyprMXBannerView that had the click event
 */
override fun onAdClicked(view: HyprMXBannerView)

/**
 * The click event on the banner has transition to an overlay
 *
 * @param ad The HyprMXBannerView that had the click event
 */
override fun onAdOpened(view: HyprMXBannerView)

/**
 * The opened overlay has been dismissed
 *
 * @param ad The HyprMXBannerView that triggered the overlay
 */
override fun onAdClosed(view: HyprMXBannerView)

/**
 * The click event on the banner will open a third party application to
 * process the click
 *
 * @param ad The HyprMXBannerView that had the click event
 *
 * @deprecated it will be removed on a major future release
 */
override fun onAdLeftApplication(view: HyprMXBannerView)

/**
 * The impression event on the banner when the banner is considered visible and impressed.
 *
 * @param ad The HyprMXBannerView that had the impression event
 */
override fun onAdImpression(view: HyprMXBannerView)
```

{% endtab %}
{% endtabs %}

### Audio Banner Ad Event Callbacks (Optional) <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

#### Setting an Audio Listener on HyprMX <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

To receive audio event callbacks, implement the `HyprMXIf.HyprMXAudioAdListener` interface and set your listener object to `HyprMX.setAudioAdListener(this)`.

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

```java
public class AudioChangeDelegate implements HyprMXIf.HyprMXAudioAdListener {
  @Override
  public void onAdAudioStart() {}
  
  @Override
  public void onAdAudioEnd() {}
}

AudioDelegate hyprAudioChangeDelegate = new AudioChangeDelegate();

HyprMX.setAudioAdListener(hyprAudioChangeDelegate);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
class AudioDelegate : HyprMXIf.HyprMXAudioAdListener {
    override fun onAdAudioStart() {}
    override fun onAdAudioEnd() {}
}

val hyprAudioChangeDelegate = AudioDelegate()

HyprMX.setAudioAdListener(hyprAudioChangeDelegate)
```

{% endtab %}
{% endtabs %}

#### Handling Interruptions <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

When an Audio Banner Ad begins playing, you will receive a `onAdAudioStart` callback from your `AudioChangeDelegate`. You should use this callback to pause your application's current audio players.

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

```java
private MediaPlayer mediaPlayer = new MediaPlayer();
@Override
public void onAdAudioStart() {
    mediaPlayer.pause();
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
private var mediaPlayer = MediaPlayer()
override fun onAdAudioStart() {
    mediaPlayer?.pause()
}
```

{% endtab %}
{% endtabs %}

#### Clearing Interruptions <a href="#bannerads6.0.0-initializeinitializeabannerview" id="bannerads6.0.0-initializeinitializeabannerview"></a>

When an Audio Banner Ad has completed playback, you will receive a `onAdAudioEnd` callback from your `AudioChangeDelegate`. You should use this callback to resume the AudioSession within your app and resume your Application's audio players.

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

```java
private MediaPlayer mediaPlayer = new MediaPlayer();
@Override
public void onAdAudioEnd() {
    mediaPlayer.play();
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
private var mediaPlayer = MediaPlayer()
override fun onAdAudioEnd() {
    mediaPlayer?.play()
}
```

{% endtab %}
{% endtabs %}

### Updating Ad Size / Reloading <a href="#bannerads6.0.0-updatingupdatingadsize-reloading" id="bannerads6.0.0-updatingupdatingadsize-reloading"></a>

You can reload another banner at any time by calling `loadAd()` on the bannerView. You can also update your `adSize` before loading a new ad by updating the `bannerView.adSize` property.

### Destroying <a href="#bannerads6.0.0-updatingupdatingadsize-reloading" id="bannerads6.0.0-updatingupdatingadsize-reloading"></a>

When the hosting `Activity` or `Fragment` is destroyed, or you are done with the banner view, and it is no longer visible and attached, be sure to also destroy the `HyprMXBannerView` by calling:

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

```java
bannerView.destroy();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
bannerView.destroy()
```

{% endtab %}
{% endtabs %}