Interstitial ads custom events

Prerequisites

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

You may also want to first read about loading an interstitial ad and how mediation works.

Define a custom event

In the following example, you'll first create an interstitial custom event within AdMob mediation. This requires that you define a custom event that points to that specific class in your app through the AdMob UI, then implement a CustomEventInterstitial to serve a view. This example defines a custom event to display ads from the sample ad network.

The custom event must be defined in the AdMob UI. Follow these instructions to create a custom event.

Make sure the value you give for the Class Name has a full path. Parameter should contain any information needed to make an ad request to the network you're implementing in the custom event.

Request an interstitial

To request an interstitial, define a class that implements CustomEventInterstitial; we'll call this class SampleCustomEventInterstitial . When the custom event is chosen from the mediation flow, mediation calls the requestInterstitialAd() method on the class name you provided in the settings. You can use the parameter provided in this method to make an interstitial request to your desired network. The following example shows how to request an interstitial from the sample ad network via a custom event:

Here's an example SampleCustomEventInterstitial implementation:

public class SampleCustomEventInterstitial implements CustomEventInterstitial {

    /** Represents a SampleInterstitial. */
    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(Context context,
            CustomEventInterstitialListener listener,
            String serverParameter,
            MediationAdRequest mediationAdRequest,
            Bundle customEventExtras) {
        /**
         * In this method, you should:
         * 1. Create your interstitial ad.
         * 2. Set your ad network's listener.
         * 3. Make an ad request.
         */

        sampleInterstitial = new SampleInterstitial(context);

        // Here we're assuming the serverParameter is the ad unit for the sample ad network.
        sampleInterstitial.setAdUnit(serverParameter);

        // Implement a SampleAdListener and forward callbacks to
        // AdMob.
        sampleInterstitial.setAdListener(new SampleCustomInterstitialEventForwarder(listener));

        // Make an ad request.
        sampleInterstitial.fetchAd(createSampleRequest(mediationAdRequest));
    }

    /**
     * Helper method to create a SampleAdRequest.
     * @param mediationAdRequest The mediation request with targeting information.
     * @return The created SampleAdRequest.
     */
    private SampleAdRequest createSampleRequest(MediationAdRequest mediationAdRequest) {
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        return request;
    }

    @Override
    public void showInterstitial() {
        // Show your interstitial ad.
        sampleInterstitial.show();
    }

    /** The event is being destroyed. Perform any necessary cleanup here. */
    @Override
    public void onDestroy() {
        if (sampleInterstitial != null) {
            sampleInterstitial.destroy();
        }
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies AdMob mediation
     * that the app is being paused.
     */
    @Override
    public void onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the
     * adapter if the developer notifies AdMob
     * mediation that the app is being resumed.
     */
    @Override
    public void onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }
}

class SampleCustomEventInterstitial : CustomEventInterstitial {

    /** Represents a SampleInterstitial.  */
    private lateinit var mSampleInterstitial: SampleInterstitial

    override fun requestInterstitialAd(context: Context,
                                       listener: CustomEventInterstitialListener,
                                       serverParameter: String,
                                       mediationAdRequest: MediationAdRequest,
                                       customEventExtras: Bundle?) {
        /**
         * In this method, you should:
         * 1. Create your interstitial ad.
         * 2. Set your ad network's listener.
         * 3. Make an ad request.
         */

        mSampleInterstitial = SampleInterstitial(context)

        // Here we're assuming the serverParameter is the ad unit for the sample ad network.
        mSampleInterstitial.adUnit = serverParameter

        // Implement a SampleAdListener and forward callbacks to
        // AdMob mediation.
        mSampleInterstitial.adListener = SampleCustomInterstitialEventForwarder(listener)

        // Make an ad request.
        mSampleInterstitial.fetchAd(createSampleRequest(mediationAdRequest))
    }

    /**
     * Helper method to create a [SampleAdRequest].
     * @param mediationAdRequest The mediation request with targeting information.
     * *
     * @return The created [SampleAdRequest].
     */
    private fun createSampleRequest(mediationAdRequest: MediationAdRequest): SampleAdRequest {
        val request = SampleAdRequest()
        request.testMode = mediationAdRequest.isTesting
        request.keywords = mediationAdRequest.keywords
        return request
    }

    override fun showInterstitial() {
        // Show your interstitial ad.
        mSampleInterstitial.show()
    }


    /** The event is being destroyed. Perform any necessary cleanup here. */
    override fun onDestroy() {
        mSampleInterstitial.destroy()
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies AdMob mediation that
     * the app is being paused.
     */
    override fun onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the adapter if
     * the developer notifies AdMob mediation that
     * the app is being resumed.
     */
    override fun onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }
}

The interstitial custom event interface requires you to implement the showInterstitial() method. Mediation invokes this method when you tell the Google Mobile Ads SDK to show the interstitial ad.

Send ad network extras for custom event requests (optional)

If you need to send extra parameters to your custom event, use the addCustomEventExtrasBundle() method of the AdRequest.Builder class. You must pass in your custom event adapter class and a bundle of the extras expected by your custom event adapter.

Here is a code snippet that shows how to pass a SampleExtra parameter for the SampleCustomEventInterstitial class defined earlier:

Bundle extras = new Bundle();
extras.putBoolean("SampleExtra", true);

AdRequest request = new AdRequest.Builder()
        .addCustomEventExtrasBundle(SampleCustomEventInterstitial.class, extras)
        .build();

If you don't call addCustomEventExtrasBundle() with the correct custom event class and a bundle for a custom event request, the bundle parameter received by the adapter will be null.

Notify AdMob mediation

Implement your network's ad listener and invoke the relevant callbacks on CustomEventListener to send messages back to AdMob mediation.

You're required to notify AdMob mediation of all callbacks. AdMob mediation supports the following callbacks:

This example SampleCustomInterstitialEventForwarder class implements the SampleAdListener interface to forward the callbacks from the sample ad network:

public class SampleCustomInterstitialEventForwarder extends SampleAdListener {
    private CustomEventInterstitialListener mInterstitialListener;

    /**
     * Creates a new SampleInterstitialEventForwarder.
     * @param listener An AdMob CustomEventInterstitialListener that should
     *                 receive forwarded events.
     */
    public SampleCustomInterstitialEventForwarder(CustomEventInterstitialListener listener) {
        this.mInterstitialListener = listener;
    }

    @Override
    public void onAdFetchSucceeded() {
        mInterstitialListener.onAdLoaded();
    }

    public static final String SAMPLE_NETWORK_DOMAIN = "www.sample-mediation.net";

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
      switch (errorCode) {
        case UNKNOWN:
          interstitialListener.onAdFailedToLoad(new AdError(AdRequest.ERROR_CODE_INTERNAL_ERROR,
                  "Sample network returns an unknown error.", SAMPLE_NETWORK_DOMAIN));
          break;
        case BAD_REQUEST:
          interstitialListener.onAdFailedToLoad(new AdError(AdRequest.ERROR_CODE_INVALID_REQUEST,
                  "Sample network returns HTTP 301 error.", SAMPLE_NETWORK_DOMAIN));
          break;
        case NETWORK_ERROR:
          interstitialListener.onAdFailedToLoad(new AdError(AdRequest.ERROR_CODE_NETWORK_ERROR,
                  "Sample network returns a network error.", SAMPLE_NETWORK_DOMAIN));
          break;
        case NO_INVENTORY:
          interstitialListener.onAdFailedToLoad(new AdError(AdRequest.ERROR_CODE_NO_FILL,
                  "Sample network returns a no-fills error.", SAMPLE_NETWORK_DOMAIN));
          break;
      }
    }

    @Override
    public void onAdFullScreen() {
        mInterstitialListener.onAdOpened();
    }

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

class SampleCustomInterstitialEventForwarder(private val mInterstitialListener: CustomEventInterstitialListener)
        : SampleAdListener() {

    override fun onAdFetchSucceeded() {
        mInterstitialListener.onAdLoaded()
    }

    const val SAMPLE_NETWORK_DOMAIN = "www.sample-mediation.net"

    override fun onAdFetchFailed(errorCode: SampleErrorCode) {
        when (errorCode) {
            UNKNOWN -> interstitialListener.onAdFailedToLoad(AdError(AdRequest.ERROR_CODE_INTERNAL_ERROR,
                "Sample network returns an unknown error.", SAMPLE_NETWORK_DOMAIN))
            TSResponse.BAD_REQUEST -> interstitialListener.onAdFailedToLoad(AdError(AdRequest.ERROR_CODE_INVALID_REQUEST,
                "Sample network returns HTTP 301 error.", SAMPLE_NETWORK_DOMAIN))
            NETWORK_ERROR -> interstitialListener.onAdFailedToLoad(AdError(AdRequest.ERROR_CODE_NETWORK_ERROR,
                "Sample network returns a network error.", SAMPLE_NETWORK_DOMAIN))
            NO_INVENTORY -> interstitialListener.onAdFailedToLoad(AdError(AdRequest.ERROR_CODE_NO_FILL,
                "Sample network returns a no-fills error.", SAMPLE_NETWORK_DOMAIN))
        }
    }

    override fun onAdFullScreen() {
        mInterstitialListener.onAdOpened()
    }

    override fun onAdClosed() {
        mInterstitialListener.onAdClosed()
    }
}

This completes the custom events implementation for interstitial ads. The full example is available on GitHub. You can use it with an ad network that is already supported or modify it to display custom interstitial ads.