Rewarded Ads Custom Events

This guide is for publishers looking to use AdMob mediation to show rewarded ads from a network that is not directly supported in the AdMob UI.

Rewarded ad custom events allow you to write a custom mediation adapter to display rewarded ads from a third-party ad network. In this guide, we'll walk through how to write a custom event to request ads from a sample SDK we developed. You can find the full source for the sample SDK on GitHub.

Prerequisites

Creating a custom event

To define a custom event, you must first create it in the AdMob UI. You can find instructions for creating a custom event in Add a custom event.

Once defined, the custom event adapter points to a class within your app that implements the Adapter interface to serve a rewarded ad. The custom event also lists a server parameter that is passed to your rewarded adapter.

Here is a screenshot showing some sample custom event settings:

The screenshot has the following entries:

Class Name
The fully-qualified name of the class that implements the custom event adapter.
Label
A unique name defining the ad source.
Parameter
An optional string argument passed to your custom event adapter.

Implementing the custom event

A custom event is a class that implements Adapter to serve third-party ads. The steps below implement a custom event to request and display rewarded ads from the Sample Ad Network.

Report version numbers

All custom events must report to the Google Mobile Ads SDK both the version of the custom event itself and the version of the third-party SDK the custom event interfaces with. Versions are reported as VersionInfo:

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

public class SampleAdNetworkCustomEvent extends Adapter implements
    SampleAdNetworkInitCompletionListener, SampleRewardedVideoAdListener {
...
    @Override
    public VersionInfo getVersionInfo() {
        String versionString = SampleAdNetwork.VERSION_NAME;
        String splits[] = versionString.split("\\.");
        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);
    }

    @Override
    public VersionInfo getSDKVersionInfo() {
        String versionString = com.SampleAdNetwork.VERSION_NAME;
        String splits[] = versionString.split("\\.");
        int major = Integer.parseInt(splits[0]);
        int minor = Integer.parseInt(splits[1]);
        int micro = Integer.parseInt(splits[2]);
        return new VersionInfo(major, minor, micro);
    }
...
}

Initialize the adapter

Upon an app's initialization of the Google Mobile Ads SDK, initialize() is invoked on all adapters and custom events configured for the app within the AdMob UI. Custom events should perform any required initialization or set up for the third-party ads SDK within this method.

The MediationConfiguration argument provides information on all placements configured for the app within the AdMob UI.

Report either a successful or failed initialization to the Google Mobile Ads SDK by invoking onInitializationSucceeded or onInitializationFailed on the InitializationCompleteCallback argument provided in the initialize() call.

The following code snippet initializes the Sample Ads SDK, preparing it to handle ad requests:

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

public class SampleAdNetworkCustomEvent extends Adapter implements
    SampleAdNetworkInitCompletionListener, SampleRewardedVideoAdListener {

    private static final String SAMPLE_AD_UNIT_KEY = "parameter";

    private InitializationCompleteCallback initializationCallback;

    @Override
    public void initialize(Context context,
        InitializationCompleteCallback initializationCompleteCallback,
        List<MediationConfiguration> mediationConfigurations) {

        if (!(context instanceof Activity)) {
            // Context not an Activity context, fail the initialization.
            initializationCompleteCallback.onInitializationFailed(
                "Sample SDK requires an Activity context to initialize");
            return;
        }

        List<String> adUnitIDs = new ArrayList<>();
        for (MediationConfiguration configuration : mediationConfigurations) {
            if (configuration.getFormat() == AdFormat.REWARDED) {
                adUnitIDs.add(configuration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY));
            }
        }

        if (adUnitIDs.isEmpty()) {
            initializationCompleteCallback.onInitializationFailed(
                "Sample SDK requires an Activity context to initialize");
        }

        this.initializationCallback = initializationCompleteCallback;

        // Initialize the Sample SDK.
        SampleRewardedVideo.initialize((Activity) context, adUnitIDs, this);
    }

    @Override
    public void OnInitSucceeded() {
        this.initializationCallback.onInitializationSucceeded();
    }
}

Request a rewarded ad

Requests made by your app to load a rewarded ad invoke the loadRewardedAd() method of the custom event.

Report either a successful or failed ad load to the Google Mobile Ads SDK by invoking onSuccess or onFailure on the MediationAdLoadCallback argument provided in the loadRewardedAd() call. When reporting a successful ad load, provide a reference to an object that conforms to MediationRewardedAd. Invocation of the onSuccess method returns a MediationRewardedAdCallback. Custom events should maintain reference to this object to notify the Google Mobile Ads SDK of ad lifecycle events. This is shown in further detail in the Show the ad section.

Here's an example implementation of loadRewardedAd():

...
import com.google.ads.mediation.sample.sdk.SampleRewardedVideo;
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
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 SampleAdNetworkCustomEvent extends Adapter implements
    SampleAdNetworkInitCompletionListener, MediationRewardedAd {
    private static final String SAMPLE_AD_UNIT_KEY = "parameter";
    private InitializationCompleteCallback initializationCallback;
    private MediationRewardedAdCallback rewardedAdCallback;
...
    @Override
    public void loadRewardedAd(MediationRewardedAdConfiguration adConfiguration,
        MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> MediationAdLoadCallback) {
        // Gets the custom event parameter from thd ad configuration.
        String adUnit = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);
        if (SampleRewardedVideo.isAdAvailable()) {
            this.rewardedAdCallback = MediationAdLoadCallback.onSuccess(this);
        } else {
            MediationAdLoadCallback.onFailure("No fill.");
        }
    }
...
}

Show the ad

The Google Mobile Ads SDK may call the showAd() method of your custom event any time after the custom event notifies the Google Mobile Ads SDK of a successful ad load. Upon invocation of this method, the adapter should display the rewarded ad.

...
public class SampleAdNetworkCustomEvent extends Adapter implements
    SampleAdNetworkInitCompletionListener, MediationRewardedAd {
...
    private MediationRewardedAdCallback rewardedAdCallback;
...
    @Override
    public void showAd(Context context) {
        // Show the rewarded ad.
        if (SampleRewardedVideo.isAdAvailable()) {
            // Rewarded ad available, show ad.
            SampleRewardedVideo.showAd();
        }
    }
...
}

Report ad events

After displaying the ad, the custom event should report ad lifecycle events as appropriate to the Google Mobile Ads SDK using the MediationRewardedAdCallback provided at successful ad load time.

...
public class SampleAdNetworkCustomEvent extends Adapter implements
    SampleAdNetworkInitCompletionListener, MediationRewardedAd {
...
    private MediationRewardedAdCallback rewardedAdCallback;
...
    @Override
    public void showAd(Context context) {
        // Show the rewarded ad.
        if (SampleRewardedVideo.isAdAvailable()) {
            // Rewarded ad available, show ad.
            SampleRewardedVideo.showAd();
        } else {
            // Report that ad cannot be shown.
            this.rewardedAdCallback.onAdFailedToShow("Ad is unavailable to show.");
        }
    }

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

    @Override
    public void onAdRewarded(final String rewardType, final int amount) {
        /*
         * AdMob requires a reward item with a reward type and
         * amount to be sent when sending the rewarded callback. If your SDK does
         * not have a reward amount you need to do the following:
         *
         * 1. AdMob provides an ability to override the
         *    reward value in the UI. Ask the publisher to override the reward
         *    value on AdMob's UI.
         * 2. Send a reward item with default values for the type (an empty string
         *    "") and reward amount (1).
         */
        this.rewardedAdCallback.onUserEarnedReward(new SampleRewardItem(rewardType,
            amount));
    }

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

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

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

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

Ad event Description
onAdOpened() Notifies the Google Mobile Ads SDK that the ad opened.
onAdFailedToShow() Notifies the Google Mobile Ads SDK that the rewarded ad failed to show.
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 closed.