Rewarded ads custom events

Prerequisites

Before you can create custom events, you need to integrate the rewarded ad format into your app.

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 configured for the app within the AdMob UI. This functionality is not currently supported within custom events, but the Adapter class does require the method to be implemented. To work around this, invoke the onInitializationSucceeded() callback as a placeholder implementation.

...
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
        SampleRewardedVideoAdListener {

    private static final String SAMPLE_AD_UNIT_KEY = "parameter";

    private InitializationCompleteCallback initializationCallback;

    @Override
    public void initialize(Context context,
            InitializationCompleteCallback initializationCompleteCallback,
            List<MediationConfiguration> mediationConfigurations) {
        // This method currently does not get invoked. As a placeholder, call
        // onInitializationSucceeded(). This way, when this feature gets
        // implemented in the future, your custom events returns a success
        // callback for initialization instead of timing out, which would
        // delay the Google Mobile Ads SDK calling back your application with
        // the initialization complete callback.
        initializationCompleteCallback.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";
    // Domain for your custom event. Typically represented by the package name.
    private static final String DOMAIN = "com.google.ads.mediation.sample.customevent";
    // Error code indicating the Sample SDK does not have an ad available.
    private static final int ERROR_CODE_NOT_AVAILABLE = 0;

    private InitializationCompleteCallback initializationCallback;
    private MediationRewardedAdCallback rewardedAdCallback;
...
    @Override
    public void loadRewardedAd(MediationRewardedAdConfiguration adConfiguration,
        MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallback) {
        // Gets the custom event parameter from thd ad configuration.
        String adUnit = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);
        if (SampleRewardedVideo.isAdAvailable()) {
            this.rewardedAdCallback = adLoadCallback.onSuccess(this);
        } else {
            AdError error = new AdError(ERROR_CODE_NOT_AVAILABLE,
                    "Sample SDK does not have a rewarded video ad available", DOMAIN);
            adLoadCallback.onFailure(error);
        }
    }
...
}

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.
            AdError error = new AdError(ERROR_CODE_NOT_AVAILABLE,
                    "Sample SDK does not have a rewarded video ad available", DOMAIN);
            this.rewardedAdCallback.onAdFailedToShow(error);
        }
    }

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