PubMatic Adapter for DFP Android SDK (Version 5.3.2)

Document created by Shrawan.Gupta on Mar 13, 2018Last modified by Shrawan.Gupta on Mar 14, 2018
Version 1Show Document
  • View in full screen mode


To use PubMatic as a client-side demand source, publishers can use third-party mediation support in DFP SDK to integrate PubMatic Android SDK for Banner & Interstitial ads. PubMatic provides client side mediation adapter to integrate PubMatic SDK with DFP SDK. Publishers can easily integrate PubMatic adapter and DFP SDK into mobile application with minimal code changes.


This document provides guidelines for writing PubMatic adapters for DFP.


The following diagram illustrates the call flow of mediation ad serving.

Mediation Ad Serving Call Flow

  1. DFP SDK, which is integrated into application, requests ad from DFP ad server.
  2. DFP responds back with mediation response containing Custom Event Class names (e.g.PMCustomEventBanner) and server parameter containing PubMatic’s ad tag information. We recommend you specify this parameter as <pubId_siteId_adTagId>.
  3. When the mediation response is received, DFP SDK initializes PubMatic adapter using class name, and passes the server parameter.
  4. PubMatic adapter initializes PubMatic SDK with the details received (pubId, siteIs & adTagId) from the server parameter.
  5. PubMatic SDK then makes a call to PubMatic ad server requesting an ad.
  6. PubMatic ad server responds with an ad.
  7. PubMatic SDK delegates control to the adapter.
  8. The adapter then hands over rendered ad to DFP SDK & informs the result with standard callbacks.

Configuring the PubMatic Network on DFP Portal

Use the following steps to configure Custom Event on DFP portal:

  1. Log in to the DFP account.
  2. Navigate to the Delivery >Yield groups tab and create a yield group.
  3. Select the Ad format(Banner) and Environment(Mobile app) you wish to target with this yield group.
  4. Select inventory sizes and add targeting criteria, if any.
  5. Click Add another yield partner to add PubMatic as a third-party mediation partner. Select Yield partner as PubMatic, if already defined, otherwise, click Create a new yield partner and add PubMatic as a new yield partner.
  6. Select integration type as Custom event mediation. and specify Operating system as Android.
  7. Add your custom event in Class Name, e.g com.pubmatic.adapter.dfp.PMCustomEventBanner and specify PubMatic’s tag in parameter section in <pubId_siteId_adId> format. You may also specify Label & Default CPM.
  8. Click SAVE button.

NOTE: Please enter the Custom Event Class name and parameter in the exact same format mentioned above. Any changes in these may cause failure in initializing PubMatic adapter.

PubMatic Banner Adapter for DFP SDK

Integrate the DFP SDK (Google-Mobile-Ads-SDK) in your project. This document refers to DFP SDK version 11.8.0


You can monetize your application with ad networks, not directly supported by mediation, through custom events. A custom event is implemented through CustomEventBanner interface.

  1. Integrate the PubMatic banner SDK in your app by adding below line inside the build.gradle file of your application. Refer PubMatic SDK doc for latest released version.
    compile 'com.github.PubMatic.pubmatic-sdk-android:banner-sdk:5.3.2'

    It requires maven dependency needs to be added in your project's build.gradle.

    allprojects {
        repositories {
            maven {
                url ""
  2. Create a class that implements CustomEventBanner in your application. (e.g PMCustomEventBanner – here PM stands for PubMatic)
  3. Make PMBannerAdView and CustomEventBannerListener as a member variables.
    * PubMatic Banner Ad View

    private PMBannerAdView mPMBanner;

    * DFP Banner ad event listener

    private CustomEventBannerListener mDFPBannerListener;
  4. Implement CustomEventBanner from DFP SDK and RequestListener, ActivityListener, RichMediaListener from PubMatic SDK.
    public class PMCustomEventBanner implements CustomEventBanner, RequestListener, ActivityListener, RichMediaListener, FeatureSupportHandler {

       //Override all methods of implemented interfaces
  5. Inside requestBannerAd() method of CustomEventBanner, implement code that requests an Ad to PubMatic SDK for Banner ad format. Please refer PubMatic SDK Guide to create instance of PMBannerAdView view and sending Ad request. Please refer to the following code.
    public void requestBannerAd(Context context, CustomEventBannerListener customEventBannerListener, String serverParameter, AdSize adSize, MediationAdRequest mediationAdRequest, Bundle bundle) {
        mDFPBannerListener = customEventBannerListener;

        // PubMatic ad tag details are configured at DFP portal in the form of
        // <Pub_ID>_<Site_ID>_<Ad_ID>
        // Split the serverParameter to get the same parameters
        String[] serverParam = serverParameter.split("_");

        // check for the valid server parameters
        if (serverParam != null && serverParam.length >= 3) {

            // Initialize PubMatic's Banner AdView
            mPMBanner = new PMBannerAdView(context);

            // Optional: Set true for opening the landing page in internal browser.
            // It can be changed to false, if landing page is supposed to be open in external browser

            // Set listener to get ad request's success/failure callbacks

            // Set listener to get RichMedia related callbacks like onExpanded

            // Set listener to listen the activity related events like leaving screen

            // Set feature support listener to provide access to CALL/SMS/CALENDAR/PICTURE in case
            // of MRAID ads.

            // Create the PubMatic Banner ad request for PubMatic SSP channel in PubMatic SDK
            PMBannerAdRequest adRequest = PMBannerAdRequest.createPMBannerAdRequest(serverParam[0], serverParam[1], serverParam[2]);

            // Create PUBAdSize based on AdSize values from server parameters
            adRequest.setAdSize(new PMAdSize(adSize.getWidth(), adSize.getHeight()));

            // Make a banner ad request to PubMatic SDK

        } else if (mDFPBannerListener != null) {
  6. When your ad loads successfully, you must notify DFP SDK by calling the onAdLoaded(<PMBannerAdView>) method on the custom event listener Please refer to the following code:
    public void onReceivedAd(PMBannerAdView pmBannerAdView) {
        if (mDFPBannerListener != null) {
  7. Similarly, you must notify the delegate when your ad fails to load by calling onAdFailedToLoad(<ErrorCode>) method.
    public void onFailedToReceiveAd(PMBannerAdView pmBannerAdView, PMError pmError) {
        if (mDFPBannerListener != null) {
            if (pmError != null && pmError.getCode() > 0) {
                switch (pmError.getCode()) {
                    case PMError.INVALID_REQUEST:
                    case PMError.NETWORK_ERROR:
                    case PMError.NO_ADS_AVAILABLE:
                    case PMError.INTERNAL_ERROR:
  8. (Optional) Notify the DFP listener for user interaction events via the corresponding methods:

    - onAdClicked()
    - onAdLoaded()
    - onAdClosed()
    - onAdOpened()


  9. (Optional) Notify the delegate if the user leaves the application from a banner via the onAdLeftApplication() method.


  10. Implement the onDestroy() method if your custom event requires any sort of cleanup and call mPMBanner.destroy(). Please refer sample code below.

    public void onDestroy() {
        if (mPMBanner != null) {
            mPMBanner = null;
  11. Finally, on the DFP web interface, create an SDK mediation creative for your line item with the "Custom event" network. Place the class name of your custom event (e.g com.pubmatic.adapter.dfp.PMCustomEventBanner) in the “Class name" field.

  12. Once you've completed these steps, the DFP SDK will be able to automatically instantiate your class when your application is running. You do not need to explicitly instantiate any of these classes in your application code.