Custom Events

This guide is intended for publishers looking to use DFP Mediation to:

  • show ads from a network that is not directly supported in the DFP user interface
  • show a custom view instead of an ad

Custom events allow you to write a custom mediation adapter to place any view into your ad space. You can find the full source for this project on GitHub.

Prerequisites

In the following example, you'll first create a banner custom event within DFP Mediation. This requires defining a custom event that points to that specific class in your application through the DFP interface, then implementing a CustomEventBanner to serve a view. This example defines a custom event to display ads from the Sample Ad Network as in the Publishers Get Started guide.

Step 1: Define a Custom Event

The custom event must be defined in the DFP interface. You can find instructions for setting up a DFP yield group for mediation in this Help Center article.

Here is a screenshot showing some sample custom event settings:

Step 2: Request a Banner

Define a class which implements CustomEventBanner; we'll call this class SampleCustomEventBanner. When the custom event is chosen from the mediation flow, mediation calls the requestBannerAd method on the class name you provided in the settings. You can use the parameters provided in this method to make a banner request to your desired network (for our example: Sample Ad Network).

Your custom event must notify mediation via the CustomEventBannerListener interface when it loads or fails to load an ad. Otherwise, the custom event times out, and mediation moves on to the next network.

You'll also want to implement any lifecycle methods as appropriate. Mediation will forward the adapter of onPause and onResume activity events if the user calls the PublisherAdView.pause() and PublisherAdView.resume() methods. The Sample ad network doesn't include a pause or resume call, so it provides an empty implementation. Mediation will also make its best attempt to call onDestroy when the adapter is about to be destroyed. Perform any necessary cleanup here.

SampleCustomEventBanner.java

public class SampleCustomEventBanner implements CustomEventBanner {

  /** The {@link SampleAdView} representing a banner ad. */
  private SampleAdView sampleAdView;

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

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

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

  @Override
  public void requestBannerAd(Context context,
                              CustomEventBannerListener listener,
                              String serverParameter,
                              AdSize size,
                              MediationAdRequest mediationAdRequest,
                              Bundle customEventExtras) {

    sampleAdView = new SampleAdView(context);

    // Assumes that the serverParameter is the AdUnit for the Sample Network.
    sampleAdView.setAdUnit(serverParameter);

    sampleAdView.setSize(new SampleAdSize(size.getWidth(), size.getHeight()));

    // Implement a SampleAdListener and forward callbacks to mediation. The callback forwarding is
    // handled by SampleBannerEventForwarder.
    sampleAdView.setAdListener(new SampleCustomBannerEventForwarder(listener, sampleAdView));

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

  }

  private SampleAdRequest createSampleRequest(MediationAdRequest mediationAdRequest) {
    SampleAdRequest request = new SampleAdRequest();
    request.setTestMode(mediationAdRequest.isTesting());
    request.setKeywords(mediationAdRequest.getKeywords());
    return request;
  }
}

Step 3: Notify DFP Mediation

Implement the ad listener for your network and invoke the relevant callbacks on CustomEventBannerListener to send messages back to mediation. We've created the SampleCustomBannerEventForwarder class, implementing the SampleAdListener interface, to forward callbacks from the sample ad network to mediation. Mediation supports the following callbacks:

Method When to call
onAdLoaded The banner request succeeded
onAdFailedToLoad The banner request failed
onAdClicked The banner was clicked
onAdOpened The banner is rendering a full screen view
onAdClosed The user returns to the application after clicking on a banner
onAdLeftApplication The banner causes the user to leave the application

You are required to notify mediation of all callbacks.

SampleCustomEventBannerForwarder.java

public class SampleCustomBannerEventForwarder extends SampleAdListener {
    private CustomEventBannerListener mBannerListener;
    private SampleAdView mAdView;

    /**
     * Creates a new {@code SampleBannerEventForwarder}.
     * @param listener An AdMob Mediation {@link CustomEventBannerListener} that should receive
     *                 forwarded events.
     * @param adView   A {@link SampleAdView}.
     */
    public SampleCustomBannerEventForwarder(
            CustomEventBannerListener listener, SampleAdView adView) {
        this.mBannerListener = listener;
        this.mAdView = adView;
    }

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

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch (errorCode) {
            case UNKNOWN:
                mBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mBannerListener.onAdClicked();
        mBannerListener.onAdOpened();
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mBannerListener.onAdLeftApplication();
    }

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

Interstitial Custom Event

To implement an interstitial custom event, you first create an interstitial custom event within DFP Mediation, much like a banner custom event. Then implement a CustomEventInterstitial and notify mediation. This example uses the Sample Ad Network as before.

Step 1: Define a Custom Event

You can define an interstitial custom event through the DFP Interface. 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.

Step 2: Request an Interstitial

Define a class which 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 parameters 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:

SampleCustomEventInterstitial.java

public class SampleCustomEventInterstitial implements CustomEventInterstitial {

  /** Represents a {@link 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 mediation.
    sampleInterstitial.setAdListener(new SampleCustomInterstitialEventForwarder(listener));

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

  /**
   * Helper method to create a {@link SampleAdRequest}.
   * @param mediationAdRequest The mediation request with targeting information.
   * @return The created {@link 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 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.

Step 3: Notify DFP Mediation

Just as with the banner custom event example, implement your network's ad listener to forward messages back to mediation. We've created the SampleCustomInterstitialEventForwarder class, implementing the SampleAdListener interface, to forward the callbacks from the sample ad network to mediation.

SampleCustomInterstitialEventForwarder.java

public class SampleCustomInterstitialEventForwarder extends SampleAdListener {
    private CustomEventInterstitialListener mInterstitialListener;

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

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

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch (errorCode) {
            case UNKNOWN:
                mInterstitialListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mInterstitialListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mInterstitialListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mInterstitialListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mInterstitialListener.onAdOpened();
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mInterstitialListener.onAdLeftApplication();
    }

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

This completes the custom events implementation for interstitials. You can find the full example on GitHub, which you can tweak to display custom interstitials or use an ad network not already supported.

Send feedback about...

SDK for DFP Users on Android
Need help? Visit our support page.