Implementing a Rewarded Ad Adapter

A mediation adapter receives messages and requests from the Google Mobile Ads SDK and communicates with a third-party network SDK in order to fulfill those requests.

This guide is intended for ad networks looking to build a rewarded ad mediation adapter for Google Mobile Ads Mediation. A Sample SDK is used in the code snippets below for demonstration purposes. You can find a complete implementation of an adapter built for this sample SDK in our Android Mediation project. This guide explains how to build the adapter.

Define adapter class name and server parameters

Ad networks mediated through the AdMob mediation platform typically require one or more identifiers to identify a publisher. These identifiers are represented as server parameters and are defined when configuring a third-party ad network for mediation in the AdMob UI.

Prior to developing a mediation adapter, you must supply Google with your adapter class name and other required parameters to gain access for your ad network.

Implement Adapter Class

The first step is to implement the Adapter abstract class:

...
import com.google.android.gms.ads.mediation.Adapter;
...

public class SampleAdapter extends Adapter {
 ...
}

This change ensures that your class implements several methods discussed below.

Report version numbers

The adapter must report to the Google Mobile Ads SDK both the version of the adapter itself and the version of the third-party SDK. Versions are reported using VersionInfo.

Google's open source and versioned adapters use a 4-digit adapter version scheme, but VersionInfo only allows for 3 digits. To work around this, it is recommended to combine the last two digits into the patch version, as shown below:

...
import com.google.android.gms.ads.VersionInfo;
...

public class SampleAdapter extends Adapter implements SampleRewardedAdListener {
  ...
  @Override
  public VersionInfo getVersionInfo() {
    String versionString = BuildConfig.VERSION_NAME;
    String[] splits = versionString.split("\\.");

    if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    return new VersionInfo(0, 0, 0);
  }

  @Override
  public VersionInfo getSDKVersionInfo() {
    String versionString = SampleAdRequest.getSDKVersion();
    String[] splits = versionString.split("\\.");

    if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
    }

    return new VersionInfo(0, 0, 0);
  }
  ...
}

Initialize the adapter

Upon an app's initialization of the Google Mobile Ads SDK, initialize() is invoked on all adapters configured for the app within the AdMob UI.

The List<MediationConfiguration> argument provides information on all placements configured for your ad network within the AdMob UI. Use this information to initialize your ad network SDK. Once your ad network SDK is initialized, report either a successful or failed initialization to the Google Mobile Ads SDK by invoking the onInitializationSucceeded() or onInitializationFailed() method on the InitializationCompleteCallbackargument provided in the initialize() call.

...
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationConfiguration;
...

public class SampleAdapter extends Adapter {
  ...
  @Override
  public void initialize(
      Context context,
      InitializationCompleteCallback initializationCompleteCallback,
      List<MediationConfiguration> mediationConfigurations) {
    if (context == null) {
      initializationCompleteCallback.onInitializationFailed(
          "Initialization Failed: Context is null.");
      return;
    }

    // The Sample SDK doesn't have an initialization method, so this example
    // immediately reports a success callback.
    initializationCompleteCallback.onInitializationSucceeded();
  }
  ...
}

Request a rewarded ad

Use loadRewardedAd() method to request a rewarded ad. Hold a reference to the MediationAdLoadCallback, which lets you report a successful or a failed ad load to the Google Mobile Ads SDK.

The MediationRewardedAdCallback object will be available once onSuccess() is invoked, which you will later use to relay other ad events like clicks or rewards granted.

...
import com.google.ads.mediation.sample.sdk.SampleAdRequest;
import com.google.ads.mediation.sample.sdk.SampleRewardedAd;
import com.google.ads.mediation.sample.sdk.SampleRewardedAdListener;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationRewardedAd;
import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
...

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...

  /**
   * A MediationAdLoadCallback that handles any callback when a Sample rewarded
   * ad finishes loading.
   */
  private MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallBack;

  /**
   * Represents a SampleRewardedAd.
   */
  private SampleRewardedAd sampleRewardedAd;

  /**
   * Used to forward rewarded video ad events to the Google Mobile Ads SDK..
   */
  private MediationRewardedAdCallback rewardedAdCallback;

  ...

  // Hold a reference to the MediationAdLoadCallback object to report ad load
  // events to the Google Mobile Ads SDK.
  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration mediationRewardedAdConfiguration,
      MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback>
          mediationAdLoadCallback) {
    adLoadCallBack = mediationAdLoadCallback;
    MediationRewardedAdConfiguration adConfiguration = mediationRewardedAdConfiguration;

    String adUnitId = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);

    sampleRewardedAd = new SampleRewardedAd(adUnitId);
    SampleAdRequest request = new SampleAdRequest();
    sampleRewardedAd.setListener(this);
    sampleRewardedAd.loadAd(request);
  }

  // Hold a reference to the MediationRewardedAdCallback object to report ad
  // lifecycle events to the Google Mobile Ads SDK.
  @Override
  public void onRewardedAdLoaded() {
    rewardedAdCallback = mediationAdLoadCallBack.onSuccess(this);
  }

  @Override
  public void onRewardedAdFailedToLoad(SampleErrorCode error) {
    mediationAdLoadCallBack.onFailure(error.toString());
  }
  ...
}

Show the ad

The Google Mobile Ads SDK may call the showAd() method of your adapter any time after the SDK is notified of a successful ad load. The adapter should display the rewarded ad. If for any reason the ad can't be shown, call the onAdFailedToShow() callback.

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void showAd(Context context) {
    if (!(context instanceof Activity)) {
      rewardedAdCallback.onAdFailedToShow(
          "An activity context is required to show Sample rewarded ad.");
      return;
    }
    Activity activity = (Activity) context;

    if (!sampleRewardedAd.isAdAvailable()) {
      rewardedAdCallback.onAdFailedToShow("No ads to show.");
      return;
    }
    sampleRewardedAd.showAd(activity);
  }
  ...
}

Report ad events to the Mobile Ads SDK

After displaying the ad, the adapter should report ad lifecycle events as appropriate to the Google Mobile Ads SDK using theMediationRewardedAdCallback object provided at successful ad load time.

Typically, these callbacks are forwarded from callbacks methods fired by your ad network SDK. This example implements the Sample SDK callbacks and maps them to the callbacks available on MediationRewardedAdCallback.

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void onAdRewarded(final String rewardType, final int amount) {
    RewardItem rewardItem =
        new RewardItem() {
          @Override
          public String getType() {
            return rewardType;
          }

          @Override
          public int getAmount() {
            return amount;
          }
        };
    rewardedAdCallback.onUserEarnedReward(rewardItem);
  }

  @Override
  public void onAdClicked() {
    rewardedAdCallback.reportAdClicked();
  }

  @Override
  public void onAdFullScreen() {
    rewardedAdCallback.onAdOpened();
    rewardedAdCallback.onVideoStart();
    rewardedAdCallback.reportAdImpression();
  }

  @Override
  public void onAdClosed() {
    rewardedAdCallback.onAdClosed();
  }

  @Override
  public void onAdCompleted() {
    rewardedAdCallback.onVideoComplete();
  }
  ...
}

The ad events that should be reported to the Google Mobile Ads SDK are detailed below:

Ad event Description
onAdOpened() Notifies the Google Mobile Ads SDK that the ad will be opened.
onVideoStart() Notifies the Google Mobile Ads SDK that a rewarded ad started playing.
reportAdImpression() Notifies the Google Mobile Ads SDK that an impression occurred on the ad.
onVideoComplete() Notifies the Google Mobile Ads SDK that the rewarded ad finished playing.
onUserEarnedReward() Notifies the Google Mobile Ads SDK that the user has earned a reward.
reportAdClicked() Notifies the Google Mobile Ads SDK that the ad has been clicked.
onAdClosed() Notifies the Google Mobile Ads SDK that the ad is closed.
onAdFailedToShow() Notifies the Google Mobile Ads SDK that the ad failed to show.