PubMatic Banner Adapter for DFP Android SDK (Version 5.3.2)

Document created by Shrawan.Gupta on Mar 13, 2018Last modified by david.simerly on Mar 27, 2018
Version 7Show Document
  • View in full screen mode

Introduction

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 ad. PubMatic provides client side mediation adapter to integrate the PubMatic SDK with the DFP SDK. Using the guidelines provided below, publishers can easily integrate a PubMatic adapter and DFP SDK into a mobile app with minimal code changes. The following diagram illustrates the call flow of mediation ad serving. The following diagram illustrates the call flow of mediation ad serving.

Download the PubMatic Banner Adapter for Android source code and sample app to use with the steps below.

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 (for example, PMCustomEventBanner), and server parameter containing PubMatic’s ad tag information. We recommend you specify this parameter as <pubId_siteId_adTagId>.
  3. DFP SDK initializes the PubMatic adapter using the class name when it receives the mediation response, then passes the server parameter.
  4. PubMatic adapter initializes PubMatic SDK with the details received (that is, pubId, siteId, and adId), 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 and informs the result with standard callbacks.

 

Configuring the PubMatic Network on DFP Portal

Use the following steps to configure the 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. Choose Add another yield partner to add PubMatic as a third-party mediation partner. Select Yield partner as PubMatic, if already defined, otherwise, select Create a new yield partner and add PubMatic as a new yield partner.
  6. Select Integration type > Custom event mediation then select Operating system > Android. You can also enter a Label if needed.
  7. Add the name of your custom event in Class Name (for example, PMCustomEventBanner), then specify PubMatic’s tag in the Parameter field in <pubId_siteId_adId> format. You can also specify Default CPM if needed.
  8. Choose SAVE AND ACTIVATE.

Be sure to enter a correct Custom Event Class name and ensure that the parameter is in the exact same format as mentioned above. Any difference between what you enter here and the actual class name in your code could cause the PubMatic adapter to fail initialization.

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

 

Monetize your app with ad networks that mediation does not directly support by using DFP Custom Events. Implement a custom event using the CustomEventBanner interface.

Download the PubMatic Banner Adapter for Android source code and sample app to use with the steps below.

  1. Integrate the PubMatic banner SDK in your app by adding the following line to your app's build.gradle file. See the PubMatic SDK Developer Guide for the latest released version:
    compile 'com.github.PubMatic.pubmatic-sdk-android:banner-sdk:5.3.2'

    Also add the required maven dependency to your project's build.gradle:

    allprojects {
        repositories {
            google()
            maven {
                url "https://jitpack.io"
            }
        }
    }
  2. Create a class that implements CustomEventBanner in your application; for example, PMCustomEventBanner (here "PM" stands for PubMatic).
  3. Add 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 the DFP SDK and RequestListener, FeatureSupportHandler, ActivityListener, and RichMediaListener from the PubMatic SDK.
    public class PMCustomEventBanner implements CustomEventBanner, RequestListener, ActivityListener, RichMediaListener, FeatureSupportHandler {

       //Override all methods of implemented interfaces
    }
  5. Inside the requestBannerAd() method of CustomEventBanner, implement code that requests a Banner Ad from PubMatic SDK. See the PubMatic SDK Developer Guide to create an instance of PMBannerAdView view and learn more details about sending an ad request. Your code may be similar to the following:
    @Override
    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
            mPMBanner.setUseInternalBrowser(true);

            // Set listener to get ad request's success/failure callbacks
            mPMBanner.setRequestListener(this);

            // Set listener to get RichMedia related callbacks like onExpanded
            mPMBanner.setRichMediaListener(this);

            // Set listener to listen the activity related events like leaving screen
            mPMBanner.setActivityListener(this);

            // Set feature support listener to provide access to CALL/SMS/CALENDAR/PICTURE in case
            // of MRAID ads.
            mPMBanner.setFeatureSupportHandler(this);

            // 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
            mPMBanner.loadRequest(adRequest);

        } else if (mDFPBannerListener != null) {
            mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
        }
    }
  6. When your ad loads successfully, you must notify the DFP SDK by calling the onAdLoaded(<PMBannerAdView>) method on the custom event listener, as in the following example:
    @Override
    public void onReceivedAd(PMBannerAdView pmBannerAdView) {
        if (mDFPBannerListener != null) {
            mDFPBannerListener.onAdLoaded(pmBannerAdView);
        }
    }
  7. Similarly, you must notify the delegate when your ad fails to load by calling onAdFailedToLoad(<ErrorCode>) method:
    @Override
    public void onFailedToReceiveAd(PMBannerAdView pmBannerAdView, PMError pmError) {
        if (mDFPBannerListener != null) {
            if (pmError != null && pmError.getCode() > 0) {
                switch (pmError.getCode()) {
                    case PMError.INVALID_REQUEST:
                        mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
                        return;
                    case PMError.NETWORK_ERROR:
                        mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR);
                        return;
                    case PMError.NO_ADS_AVAILABLE:
                        mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL);
                        return;
                    case PMError.INTERNAL_ERROR:
                        mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
                        return;
                }
            }
        }
        mDFPBannerListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
    }
  8. Optional steps include:

    • Notify the DFP listener for user interaction events via the corresponding methods:

      - onAdClicked()
      - onAdLoaded()
      - onAdClosed()
      - onAdOpened()
    • Notify the delegate using the onAdLeftApplication() method if the user leaves the application from a banner.

  9. Implement the onDestroy() method if your custom event requires any sort of cleanup and call mPMBanner.destroy() as in the example below:

    @Override
    public void onDestroy() {
        if (mPMBanner != null) {
            mPMBanner.destroy();
            mPMBanner = null;
        }
    }

     

Once you've completed these steps, the DFP SDK can automatically instantiate your class when your app runs. You do not need to explicitly instantiate any of these classes in your application code.

 

References

⇧ Top

Outcomes