PubMatic Adapter for DFP iOS SDK (Version 5.2.0)

Document created by catherine.racette on Aug 21, 2017Last modified by catherine.racette on Sep 16, 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 DFP SDK to integrate PubMatic iOS 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.PMBannerCustomEvent) 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 tab and select a relevant line item from your order. E.g. line item for banner/interstitial ads.
  3. Click Add Creatives to add the custom event creative.
  4. Choose SDK Mediation creative type from mobile apps for the new creative.
  5. Specify the appropriate creative name, size, etc. and select Custom Event from Select network under Ad networks menu.
  6. Specify PubMatic’s tag in parameter section as <pubId_siteId_adTagId>. Add your custom event in Class Name, e.g PMBannerCustomEvent. You may also specify a label in the Label section.
  7. Click Save.

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 7.16.0

 

You can monetize your application with ad networks not directly supported by mediation through custom events. A custom event is implemented through either the GADCustomEventBanner or the GADCustomEventInterstitial protocol.

  1. Create a class that implements GADCustomEventBanner in your application. (e.g PMBannerCustomEvent – here PM stands for PubMatic)
  2. Override the -requestBannerAd:parameter:label:request: method and implement code that requests an Ad. Please refer PubMatic SDK Guide to create instance of PMBannerAdView view and sending Ad request. Please refer to the following code.
    -(void)requestBannerAd:(GADAdSize)adSize parameter:(NSString *)serverParameter label:(NSString *)serverLabel request:(GADCustomEventRequest *)request
    {
        NSArray *params = [serverParameter componentsSeparatedByString:@"_"];
        NSString *pubId = params[0];
        NSString *siteId = params[1];
        NSString *adTagId = params[2];
       
        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 customEventBanner:self didFailAd: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 DFP of the event by calling the - customEventBanner:didReceiveAd: method on the custom event object’s delegate (accessible via the delegate property). Please refer to the following code:
    -(void)bannerAdViewDidRecieveAd:(PMBannerAdView *)adView
    {
        NSLog(@"PubMatic Banner Ad received");
        [self.delegate customEventBanner:self didReceiveAd:adView];
    }
  4. Similarly, you must notify the delegate when your ad fails to load by calling - customEventBanner:didFailAd: method.
    -(void)bannerAdView:(PMBannerAdView *)adView didFailToReceiveAdWithError:(NSError *)error
    {
        NSLog(@"PubMatic Banner Ad failed");
        [self.delegate customEventBanner:self didFailAd:error];
    }
  5. (Optional) Notify the delegate of user interaction events via the corresponding delegate methods:

    -customEventBannerWasClicked:
    -customEventBannerWillPresentModal:
    -customEventBannerWillDismissModal:
    -customEventBannerDidDismissModal:

     

  6. (Optional) Notify the delegate if the user leaves the application from a banner via the - customEventBannerWillLeaveApplication: 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 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 PMBannerCustomEvent) in the “Class name" field.

     

  9. 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.

PubMatic Interstitial Adapter for DFP SDK


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

 

You can monetize your application with ad networks not directly supported by mediation through custom events. A custom event is implemented through either the GADCustomEventBanner or the GADCustomEventInterstitial protocol.

  1. Create a class that implements GADCustomEventInterstitial in your application. (E.g. PMInterstitialCustomEvent).
  2. Override the -requestInterstitialAdWithParameter:label:request: method and implement code that requests an Ad. Please refer PubMatic SDK Guide to create instance of PMInterstitialAdView view and sending Ad request. Please refer code below.
  3. Override the -presentFromRootViewController: and implement code that displays PubMatic interstitial Ad. Please refer code below.
    -(void)requestInterstitialAdWithParameter:(NSString *)serverParameter label:(NSString *)serverLabel request:(GADCustomEventRequest *)request
    {
        NSArray *params = [serverParameter componentsSeparatedByString:@"_"];
        NSString *pubId = params[0];
        NSString *siteId = params[1];
        NSString *adTagId = params[2];
       
        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 customEventInterstitial:self didFailAd:error];
            return;
        }
        else
        {
            PubMaticBannerAdRequest *pmInstlAdReq = [[PubMaticBannerAdRequest alloc] initWithPublisherId:pubId WithSiteId:siteId WithAdTagId:adTagId];
           
            self.instlAdView = [[PMInterstitialAdView alloc] initInterstitial];
            self.instlAdView.delegate = self;
            [self.instlAdView execute:pmInstlAdReq];
        }
    }
  4. You must notify DFP of all 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:


    -customEventInterstitialDidReceiveAd:

    -(void)bannerAdViewDidRecieveAd:( PMBannerAdView *)adView{
        NSLog(@"PubMatic instl Ad loaded");
        [self.delegate customEventInterstitialDidReceiveAd:self];
    }

     

    -customEventInterstitial:didFailAd:

    -(void)bannerAdView:( PMBannerAdView *)adView didFailToReceiveAdWithError:(NSError *)error{
        NSLog(@"PubMatic instl Ad failed");
        [self.delegate customEventInterstitial:self didFailAd:error];
    }

    -customEventInterstitialWillPresent:
    -customEventInterstitialWillDismiss:
    -customEventInterstitialDidDismiss:

    -(void)bannerAdViewCloseButtonPressed:(PMBannerAdView *)adView
    {
        [self.delegate customEventInterstitialWillDismiss:self];
        [adView closeInterstitial];
        [self.delegate customEventInterstitialDidDismiss:self];
    }

    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 InterstitialDidDismiss callback, your custom event should fire both - customEventInterstitialWillDismiss: and - customEventInterstitialDidDismiss: in response.

     

  5. (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 DFP SDK so that DFP can provide accurate analytics. You can do so by calling the -customEventInterstitialWasClicked: method on the custom event delegate.

     

  6. (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;
    }

     

     

  7. 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 PMInterstitialCustomEvent) in the “Class name" field.

    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.

References

Attachments

    Outcomes