PubMatic Adapter for MoPub iOS 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 iOS SDK for Banner, Interstitial 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

  1. MoPub SDK integrated with the application, requests an ad from the MoPub ad server.
  2. MoPub ad server responds back with mediation response containing Custom Event Class name (refer to section below) and server extra parameters containing PubMatic’s pubId, siteId & adId.
  3. When the mediation response is received, MoPub SDK initializes PubMatic adapter using class name, and passes 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 the 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 to 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. (Please note that Native network does not have any relation with 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 class name for the respective subclass of the MoPub CustomEvent class.

    Examples:

    For Banner: PMBannerCustomEvent
    For Interstitial: PMInterstitialCustomEvent

     

  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

Integrate MoPub SDK in your project. This document is refers to MoPub SDK version 4.11.1

  1. Create a subclass of MPBannerCustomEvent in your application. (e.g PMBannerCustomEvent – here PM stands for PubMatic)
  2. Override the -requestAdWithSize:customEventInfo: method and implement code that requests an Ad. Please refer to the PubMatic SDK Guide to create instance of PMBannerAdView view and sending an Ad request. Please refer to the following code:
    - (void)requestAdWithSize:(CGSize)size customEventInfo:(NSDictionary *)info
    {
        NSString *pubId = [info valueForKey:@"pub_id"];
        NSString *siteId = [info valueForKey:@"site_id"];
        NSString *adTagId = [info valueForKey:@"ad_tag_id"];
       
        if (!(pubId.length && siteId.length && adTagId.length)) {
            NSDictionary *userInfo = @{NSLocalizedDescriptionKey:NSLocalizedString(@"Invalid pubId/siteId/adId", nil)};
            NSError *error = [NSError errorWithDomain:@"PubMaticSDK" code:1 userInfo:userInfo];
            [self.delegate bannerCustomEvent:self didFailToLoadAdWithError:error];
            return;
        }
        else
        {
            PubMaticBannerAdRequest *pmBannerAdReq = [[PubMaticBannerAdRequest alloc] initWithPublisherId:pubId WithSiteId:siteId WithAdTagId:adTagId];
           
            self.bannerAdView = [[PMBannerAdView alloc] initWithFrame:CGRectMake(0, 0, 320, 50)];
            self.bannerAdView.autoresizingMask = UIViewAutoresizingFlexibleRightMargin | UIViewAutoresizingFlexibleWidth;
            [self.bannerAdView setLocationDetectionEnabled:YES];
            self.bannerAdView.delegate = self;
            [self.bannerAdView execute:pmBannerAdReq];
        }
    }
  3. When your ad loads successfully, you must notify MoPub of the event by calling the - bannerCustomEvent:didLoadAd: method on the custom event object’s delegate (accessible via the delegate property). Please refer to the following code:
    - (void)bannerAdViewDidRecieveAd:(PMBannerAdView *)adView
    {
        [self.delegate bannerCustomEvent:self didLoadAd:adView];
    }
  4. Similarly, you must notify the delegate when your ad fails to load by calling - bannerCustomEvent:didFailToLoadAdWithError: method.
    -(void)bannerAdView:(PMBannerAdView *)adView didFailToReceiveAdWithError:(NSError *)error
    {
        NSLog(@"PubMatic Banner Ad failed");
        [self.delegate bannerCustomEvent:self didFailToLoadAdWithError:error];
    }
  5. (Optional) Notify the delegate of user interaction events via the corresponding delegate methods:
    bannerCustomEventWillBeginAction:
    bannerCustomEventDidFinishAction:

    NOTE: If your implementation calls -bannerCustomEventWillBeginAction:, it must also call - bannerCustomEventDidFinishAction:.

  6. (Optional) Notify the delegate if the user leaves the application from a banner via the - bannerCustomEventWillLeaveApplication: method.

     

  7. (Optional) Implement the -dealloc method if your custom event requires any sort of cleanup. Please refer sample code below.

    -(void)dealloc{
        [self.bannerAdView reset];
        self.bannerAdView = nil;
    }

     

  8. Finally, on the MoPub web interface, create a network with the "Custom Native Network" type. Place the class name of your custom event (e.g PMBannerCustomEvent) in the “Custom Event Class" column.

     

 

 

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

 

Note: the MoPub SDK will instantiate a new MPBannerCustomEvent object on every ad call, so you can safely make changes to the custom event object's internal state without affecting subsequent ad calls.

PubMatic Interstitial Adapter for MoPub SDK

 

Integrate MoPub SDK in your project. This document is created referring to MoPub SDK version 4.11.1

  1. Create a subclass of MPInterstitialCustomEvent in your application. (E.g. PMInterstitialCustomEvent)
  2. Override the -requestInterstitialWithCustomEventInfo: method and implement code that requests an interstitial. Please refer PubMatic SDK Guide to create instance of PMInterstitialAdView and sending Ad request. Please refer code below.
    -(void)requestInterstitialWithCustomEventInfo:(NSDictionary *)info
    {
        NSString *pubId = [info valueForKey:@"pub_id"];
        NSString *siteId = [info valueForKey:@"site_id"];
        NSString *adTagId = [info valueForKey:@"ad_tag_id"];
       
        if (!(pubId.length && siteId.length && adTagId.length)) {
            NSDictionary *userInfo = @{NSLocalizedDescriptionKey:NSLocalizedString(@"Invalid pubId/siteId/adId", nil)};
            NSError *error = [NSError errorWithDomain:@"PubMaticSDK" code:1 userInfo:userInfo];
            [self.delegate interstitialCustomEvent:self didFailToLoadAdWithError:error];
            return;
        }
        else
        {
            PubMaticBannerAdRequest *pmInstlAdReq = [[PubMaticBannerAdRequest alloc] initWithPublisherId:pubId WithSiteId:siteId WithAdTagId:adTagId];
           
            instlAdView = [[PMInterstitialAdView alloc] initInterstitial];
            instlAdView.delegate = self;
            [instlAdView execute:pmInstlAdReq];
        }
    }
  3. Override the -showInterstitialFromRootViewController: and implement code that displays PubMatic interstitial Ad. Please refer code below.
    -(void)showInterstitialFromRootViewController:(UIViewController *)rootViewController
    {
        [self.delegate interstitialCustomEventWillAppear:self];
        [self.instlAdView showInterstitial];
        [self.delegate interstitialCustomEventDidAppear:self];
    }

  4. You must notify MoPub of all of the following interstitial lifecycle events, by calling the corresponding methods on the custom event object’s delegate (accessible via the delegate property), Please refer code below:

    -interstitialCustomEvent:didLoadAd:

    - (void)bannerAdViewDidRecieveAd:( PMBannerAdView *)adView{
        [self.delegate interstitialCustomEvent:self didLoadAd:self.instlAdView];
    }


    -interstitialCustomEvent:didFailToLoadAdWithError:

    - (void)bannerAdView:( PMBannerAdView *)adView didFailToReceiveAdWithError:(NSError *)error{
       
        [self.delegate interstitialCustomEvent:self didFailToLoadAdWithError:nil];
    }

     

    -interstitialCustomEventWillAppear:
    -interstitialCustomEventDidAppear:

    -interstitialCustomEventWillDisappear:
    -interstitialCustomEventDidDisappear:

    All of the methods above are required. If the ad network you are trying to use does not provide callbacks for one/more of these events, you should still call the custom event method at an appropriate time.


    For example, if an ad network only provides an adDidDisappear callback, your custom event should fire both -interstitialCustomEventWillDisappear:and -interstitialCustomEventDidDisappear: in response.

 

  1. (Optional) If the ad network is capable of notifying you when a user interacts or taps on an ad, you should forward this information to the MoPub SDK so that MoPub can provide accurate analytics. You can do so by calling the interstitialCustomEventDidReceiveTapEvent: method on the custom event delegate.
  2. (Optional) Implement the -dealloc method if your custom event requires any sort of cleanup. Please refer code below.
    - (void)dealloc
    {
        [self.instlAdView reset];
        self.instlAdView = nil;
    }
  3. On the MoPub web interface, create a network with the "Custom Native Network" type. Place the class name of your custom event (e.g. YourInterstitialCustomEvent) in the "Custom Class" column.


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

 

Note: The MoPub SDK will instantiate a new MPInterstitialCustomEvent object on every ad call, so you can safely make changes to the custom event object's internal state without affecting subsequent ad calls.

References

Attachments

    Outcomes