Interstitial Ads

This guide shows how to display Interstitial Ads in your application.

What are Interstitial Ads?

Interstitial Ad Units are full-screen, interactive ads designed to be placed between content at a natural transition point.

How to Display Interstitial 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.

Loading Interstitial Ads

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. To load an ad to a placement, follow the steps below.

If you don't have your placement information, please reach out to your account manager to configure your interstitial placements. In return, they will provide the names of the new placements.

1. Use the getPlacement API to retrieve a placement from HyprMX.

Java

interstitialPlacement = HyprMX.INSTANCE.getPlacement("YOUR_INTERSTITIAL_PLACEMENT_NAME");

Kotlin

interstitialPlacement = HyprMX.getPlacement("YOUR_INTERSTITIAL_PLACEMENT_NAME")

2. To check for availability, run the following:

Java

interstitialPlacement.loadAd(new HyprMXLoadAdListener() {
  @Override
  public void onAdLoaded(boolean isAdAvailable) {
    if(isAdAvailable) {
      // You can show the ad
   }
  }
});

Java (Lambda)

interstitialPlacement.loadAd(isAdAvailable -> {
   if(isAdAvailable) {
      // You can show the ad
   }
});

Kotlin

interstitialPlacement.loadAd { isAdAvailable ->
   if(isAdAvailable) {
      // You can show the ad
   }
}

Kotlin (Coroutines)

val isAdAvailable = interstitialPlacement.loadAd()

if(isAdAvailable) {
    // You can show the ad
}

loadAd() will call back to your listener with: isAdAvailable == true when an ad is available or false when there is no inventory.

3. To receive notification that the loaded ad has expired, implement the HyprMXPlacementExpiryListener

Java

private HyprMXPlacementExpiryListener listener = new HyprMXPlacementExpiryListener() {
  @Override
  public void onAdExpired(@NonNull Placement placement) {
      // Do something on expiration
  }
}

interstitialPlacement.setPlacementExpiryListener(listener);

Java (Lambda)

interstitialPlacement.setPlacementExpiryListener(placement -> {
   // Do something on expiration
});

Kotlin

val listener = object : HyprMXPlacementExpiryListener {
    override fun onAdExpired(placement: Placement) {
       // Do something on expiration
    }
}

interstitialPlacement.setPlacementExpiryListener(listener)

Displaying Interstitial Ads

1. Before calling showAd on a placement, you should confirm the ad state is still valid:

Java

interstitialPlacement.isAdAvailable();

Kotlin

interstitialPlacement.isAdAvailable()

When an ad is displaying, it is important to disable all in-game music and sounds so they do not interfere with the advertisements. You can disable them when your activity transitions to onStop and resume when your activity transitions to onResume.

2. When you are ready to display an ad, call showAd to begin the presentation of an ad.

Java

if (interstitialPlacement.isAdAvailable()) {
  interstitialPlacement.showAd(this);
}

Kotlin

if (interstitialPlacement.isAdAvailable()) {
  interstitialPlacement.showAd(this)
}

3. To receive display status, implement the HyprMXShowListener:

Java

/**
 * Called when an ad is shown for the given placement. Your application should pause here.
 */
@Override
public void onAdStarted(Placement placement) {}

/**
 * Called when an ad is closed. Your application should resume here.
 */
@Override
public void onAdClosed(Placement placement, boolean finished) {}

/**
 * Called when there was an error displaying the ad.
 */
@Override
public void onAdDisplayError(Placement placement, HyprMXErrors hyprMXError) {}

/**
 * Called when the ad was impressed.
 */
@Override
public void onAdImpression(Placement placement) {}

Kotlin

/**
 * Called when an ad is shown for the given placement. Your application should pause here.
 */
override fun onAdStarted(placement: Placement) {}

/**
 * Called when an ad is closed. Your application should resume here.
 */
override fun onAdClosed(placement: Placement, finished: Boolean) {}

/**
 * Called when there was an error displaying the ad.
 */
override fun onAdDisplayError(placement: Placement, hyprMXError: HyprMXErrors) {}

/**
 * Called when the ad was impressed.
 */
override fun onAdImpression(placement: Placement) {}

If you'd like, we can send server-to-server calls when ads are completed. Contact your account manager at HyprMX for more details.