PubMatic Adapter for MoPub Android SDK (Version 5.2.0)

Document created by catherine.racette on Aug 21, 2017Last modified by catherine.racette on Aug 21, 2017
Version 1Show Document
  • View in full screen mode

Introduction

 

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

 

This document provides guidelines for writing PubMatic adapters for MoPub.

 

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

Mediation Ad Serving Call Flow

Mediation Ad Serving call flow is as following:

 

  1. MoPub SDK integrated with application, requests an ad from MoPub ad server.
  2. MoPub ad server responds back with mediation response containing Custom Event Class name (Please refer section below) and server extra parameters containing PubMatic’s pubId, siteId & adId.
  3. On receiving mediation response, MoPub SDK initializes PubMatic adapter using class name, and pass all server extra parameters.
  4. PubMatic adapter initializes PubMatic SDK with server extra parameters.
  5. PubMatic SDK then makes call to PubMatic ad server requesting ad.
  6. PubMatic ad server responds with ad.
  7. PubMatic SDK delegates control to the adapter.
  8. Adapter then hands over rendered ad to MoPub SDK & informs the result with standard callbacks.

Configuring the PubMatic Network on MoPub Portal

 

Use the following steps to configure a Custom Event on the MoPub portal:

  1. Log in into your MoPub account.
  2. Navigate to the Networks tab and click Add a Network.
  3. On the Add a network pop-up, click Custom Native Network.

    Note: Native Network does not have any relation to Native Ad format.

  4. Give a suitable name to PubMatic custom network.

     

  5. In the Set Up Your Inventory section, add the custom event class and data only for the native ad unit for which you want to enable PubMatic network.

     

  6. In the custom event class field add the fully qualified class name for the respective subclass of the MoPub CustomEvent class

    Examples:

    For Banner: com.pubmatic.adapter.mopub.PubMaticBannerAdapter
    For Interstitial: com.pubmatic.adapter.mopub.PubMaticInterstitialAdapter

     

  7. Use the steps below to add the Custom Event Class Data field in JSON containing PubMatic placement details:


    For all ad formats: Enter pubId, siteId & adId provided by your PubMatic account manager, in the following format.

    {"pub_id":"<value>","site_id":"<value>","ad_tag_id":"<value>"}


    Example:

    {"pub_id":"12345","site_id":"123","ad_tag_id ":"123"}


    Please enter the Custom Event Class name and data exactly in the same format mentioned above. Any changes in these may cause failure in initializing PubMatic adapter.

  8. Save the network. Please note that it may take from 15 to 30 minutes for MoPub ad server to reflect this change.

 

PubMatic Banner Adapter for MoPub SDK

  1. Create a subclass of CustomEventBanner in your application. (e.g PubMaticBannerAdapter)
  2. Override the CustomEventBanner::loadBanner method and implement code that requests a PubMatic Banner Ad. Please refer to the PubMatic SDK Guide to create an instance of PMBannerAdView and sending an Ad request. Please refer code to the following code:
    @Override
    protected void loadBanner(Context context, CustomEventBannerListener customEventBannerListener, Map<String, Object> localExtras, Map<String, String> serverExtras) {

       // Initialize PubMatic's Banner AdView
       mPMBanner = new PMBannerAdView(context);
       mPMBanner.setRequestListener(pubMaticBannerListener);
       mPMBanner.setActivityListener(pubMaticActivityListener);

       String pubId = serverExtras.get("pubId");
       String siteId = serverExtras.get("siteId");
       String adId = serverExtras.get("adId");

       mMopubBannerListener = customEventBannerListener;

       // Create the mPMBanner ad request for PubMatic SSP platform
       PubMaticBannerAdRequest adRequest = PubMaticBannerAdRequest.createPubMaticBannerAdRequest(
             context, pubId, siteId, adId);
       adRequest.setAdSize(PUBAdSize.PUBBANNER_SIZE_320x50);//Can be customized
       mPMBanner.setUseInternalBrowser(true);
       mPMBanner.execute(adRequest);
    }
  3. When your ad loads successfully, you must notify MoPub of the event by calling the CustomEventBannerListener::onBannerLoaded method . Please refer to the following code:
    @Override
    public void onReceivedAd(PMBannerAdView adView) {
        Log.d(TAG,"PubMatic : onAdReceived ");

        if(mMopubBannerListener != null){
            mMopubBannerListener.onBannerLoaded(adView);
        }
    }
  4. Similarly, you must notify Mopub when PubMatic's ad fails to load by calling CustomEventBannerListener::onBannerFailed method.
    @Override
    public void onFailedToReceiveAd(PMBannerAdView adView, int i, String ex) {
        Log.d(TAG,"PubMatic : onFailedToReceiveAd:" + ex);

        if(mMopubBannerListener != null){
            mMopubBannerListener.onBannerFailed(MoPubErrorCode.INTERNAL_ERROR);
        }
    }
  5. (Optional) Implement ActivityListener and register it to get the lifecycle callbacks from PubMatic. Notify Mopub of user interaction events via the corresponding callback methods:

    mPMBanner.setActivityListener(pubMaticActivityListener);


    private PMBannerAdView.BannerAdViewDelegate.ActivityListener pubMaticActivityListener = new PMBannerAdView.BannerAdViewDelegate.ActivityListener()
       {
           @Override
           public boolean onCloseButtonClick(PMBannerAdView arg0) {
               return false;
           }
           @Override
           public void onLeavingApplication(PMBannerAdView arg0) {
               if (mMopubBannerListener != null)
                   mMopubBannerListener.onLeaveApplication();
           }
           @Override
           public boolean onOpenUrl(PMBannerAdView arg0, String arg1) {
               if (mMopubBannerListener != null)
                   mMopubBannerListener.onBannerClicked();
               return false;
           }
       };
  6. Finally, on the MoPub web interface, create a network with the "Custom Native Network" type. Place the fully classified class name of your custom adapter (e.g PubMaticBannerAdapter) in the “Custom Event Class" column.

    Once you've completed these steps, the MoPub SDK will be able to automatically instantiate your CustomEventBanner subclass when your application is running. You do not need to instantiate any of these sub classes in your application code.

 

PubMatic Interstitial Adapter for MoPub SDK

  1. Create a subclass of CustomEventInterstitial in your application. (E.g. PubMaticInterstitialAdapter)
  2. Override the CustomEventInterstitial::loadInterstitial method and implement code that requests a PubMatic interstitial Ad. Please refer PubMatic SDK Guide to create instance of PMInterstitialAdView and sending Ad request. Please refer code below.
    @Override
    protected void loadInterstitial(Context context, CustomEventInterstitial.CustomEventInterstitialListener customEventInterstitialListener, Map<String, Object> localExtras, Map<String, String> serverExtras) {

        mMopubInterstitialListener = customEventInterstitialListener;

        String pubId = serverExtras.get("pubId");
        String siteId = serverExtras.get("siteId");
        String adId = serverExtras.get("adId");

        // Initialize PubMatic's Banner AdView
        mPMInterstitial = new PMInterstitialAdView(context);
        mPMInterstitial.setRequestListener(pubMaticInterstitialListener);
        mPMInterstitial.setActivityListener(pubMaticActivityListener);

        // Create the mPublisherInterstitialAd ad request for PubMatic SSP platform
        PubMaticBannerAdRequest adRequest = PubMaticBannerAdRequest.createPubMaticBannerAdRequest(
                context, pubId, siteId, adId);

        adRequest.setAdSize(new PUBAdSize(320, 480));//Can be customized
        mPMInterstitial.setUseInternalBrowser(true);
        mPMInterstitial.execute(adRequest);
    }
  3. When the ad loads successfully you must notify Mopub of the event by calling the CustomEventInterstitial::onInterstitialLoaded method. Please refer code below.
    @Override
    public void onReceivedAd(PMBannerAdView adView) {
        Log.d(TAG, "PubMatic :onAdReceived ");
        mMopubInterstitialListener.onInterstitialLoaded();
    }

     

  4. Override the CustomEventInterstitial::showInterstitial method in adapter as shown below, it will be called by Mopub SDK when required, also call CustomEventInterstitial::onInterstitialShown after showing Pubmatic’s interstitial Ad.
    @Override
    protected void showInterstitial() {
            mPMInterstitial.showInterstitial();
            mMopubInterstitialListener.onInterstitialShown();
        }
  5. Similarly, you must notify Mopub when PubMatic's Ad fails to load by calling CustomEventInterstitialListener::onInterstitialFailed method.
    @Override
    public void onFailedToReceiveAd(PMBannerAdView adView, int i, String ex) {
        Log.d(TAG, "PubMatic :onFailedToReceiveAd:" + ex);
        if (mPMInterstitial != null) {
            mPMInterstitial.setVisibility(View.GONE);
        }
        if (mMopubInterstitialListener != null) {
            mMopubInterstitialListener.onInterstitialFailed(MoPubErrorCode.INTERNAL_ERROR);
        }
  6. (Optional) Implement ActivityListener and register it to get the lifecycle callbacks from PubMatic. Notify Mopub of the user interaction events via the corresponding callback methods.
    mPMInterstitial.setActivityListener(pubMaticActivityListener);


    private PMBannerAdView.BannerAdViewDelegate.ActivityListener pubMaticActivityListener = new PMBannerAdView.BannerAdViewDelegate.ActivityListener()
    {
        @Override
        public boolean onCloseButtonClick(PMBannerAdView arg0) {
            if (mMopubInterstitialListener != null)
                mMopubInterstitialListener.onInterstitialDismissed();
            return false;
        }
        @Override
        public void onLeavingApplication(PMBannerAdView arg0) {
            if (mMopubInterstitialListener != null)
                mMopubInterstitialListener.onLeaveApplication();
        }
        @Override
        public boolean onOpenUrl(PMBannerAdView arg0, String arg1) {
            if (mMopubInterstitialListener != null)
                mMopubInterstitialListener.onInterstitialClicked();
            return false;
        }
    };
  7. On the MoPub web interface, create a network with the "Custom Native Network" type. Place the fully classified class name of your custom adapter (e.g. PubMaticInterstitialAdapter) in the "Custom Class" column.


    Once you've completed these steps, the MoPub SDK will be able to automatically instantiate your CustomEventInterstitial subclass when your application is running. You do not need to instantiate any of these sub classes in your application code.

References

Attachments

    Outcomes