Banner/MREC Ads

HyprMX supports Banner/MREC and Audio Banner Ad Units. This guide shows how to display these Banner Ads in your application.

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

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

Before you start, make sure you have correctly integrated and initialized the HyprMX SDK. To integrate and initialize HyprMX, see our Setup Guide.

Initialize a BannerView

BannerViews are initialized with their placement name and ad size.

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.

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.

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.

Code Initialization

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

Java

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

Kotlin

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

XML Initialization

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

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" />

Code Setting of Name/Size

Java

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

Kotlin

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

Adding Banners to your View

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

Example Using 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" />

Example using Code:

Java

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

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)

Loading Advertisements

To load a banner ad:

Java

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

Java (Lambda)

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

Kotlin

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

Kotlin (Coroutines)

val isAdAvailable = bannerView.loadAd()

// Do something

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)

To receive lifecycle callbacks on your HyprMXBannerView, implement the HyprMXBannerListener.

Java

bannerView.setListener(listener);

Kotlin

bannerView.listener = listener

Implement the HyprMXBannerListener:

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) {}

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)

Audio Banner Ad Event Callbacks (Optional)

Setting an Audio Listener on HyprMX

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

Java

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

AudioDelegate hyprAudioChangeDelegate = new AudioChangeDelegate();

HyprMX.setAudioAdListener(hyprAudioChangeDelegate);

Kotlin

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

val hyprAudioChangeDelegate = AudioDelegate()

HyprMX.setAudioAdListener(hyprAudioChangeDelegate)

Handling Interruptions

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.

Java

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

Kotlin

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

Clearing Interruptions

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.

Java

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

Kotlin

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

Updating Ad Size / Reloading

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

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:

Java

bannerView.destroy();

Kotlin

bannerView.destroy()