Rewarded Ads

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

What are Rewarded Ads?

Rewarded Ad Units reward a user within the app in exchange for completing the ad. This opt-in ad unit provides a less disruptive user experience along with high engagement from users.

How to Display Rewarded 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 Rewarded 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 rewarded placements. In return, they will provide the names of the new placements.

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

Java

rewardedPlacement = HyprMX.INSTANCE.getPlacement("YOUR_REWARDED_PLACEMENT_NAME");

Kotlin

rewardedPlacement = HyprMX.getPlacement("YOUR_REWARDED_PLACEMENT_NAME")

2. To check for availability, run the following:

Java

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

Java (Lambda)

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

Kotlin

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

Kotlin (Coroutines)

val isAdAvailable = rewardedPlacement.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
  }
}

rewardedPlacement.setPlacementExpiryListener(listener);

Java (Lambda)

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

Kotlin

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

rewardedPlacement.setPlacementExpiryListener(listener)

Displaying Rewarded Ads

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

Java

rewardedPlacement.isAdAvailable();

Kotlin

rewardedPlacement.isAdAvailable()

When an ad is displaying, it is important to disable all in-game music and sounds so they do not interfere with the ads. 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 (rewardedPlacement.isAdAvailable()) {
  rewardedPlacement.showAd(this);
}

Kotlin

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

3. To receive ad reward and display status, implement the HyprMXRewardedShowListener:

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) {}
  
/**
 * Called when the user should be rewarded for the given rewarded placement.
 */
@Override
public void onAdRewarded(Placement placement, String rewardName, Int rewardValue) {}

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

/**
 * Called when the user should be rewarded for the given rewarded placement.
 */
override fun onAdRewarded(placement: Placement, rewardName: String, rewardValue: Int) {}

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