PubMatic Adapter for DFP iOS SDK (Version 5.3.1)

Document created by Pritesh.Lad on Mar 12, 2018Last modified by Pritesh.Lad 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 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.PMCustomEventBanner) and server parameter containing PubMatic’s ad tag information. We recommend you specify this parameter as <pubId_siteId_adId>.
  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 & 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 & 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 & 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 iOS.
  7. Add your custom event in Class Name, e.g PMCustomEventBanner and specify PubMatic’s tag in parameter section in <pubId_siteId_adId> format. You may also specify Label & Default CPM.

NOTE: Please enter a correct Custom Event Class name and ensure that the parameter is in the exact same format mentioned above. Any changes in these may cause failure in initializing the 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.28.0


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

  1. Create a class that implements GADCustomEventBanner in your application. (e.g PMCustomEventBanner – here PM stands for PubMatic)
  2. Override the -requestBannerAd:parameter:label:request: method and implement code that requests an ad from PubMatic. Please refer the PubMatic SDK Guide(ToDo: pls insert SDK documentation link) to create instance of PMBannerAdView view and sending Ad request. Please refer 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 *adId = params[2];
        if (!(pubId.length && siteId.length && adId.length)) {
            NSDictionary *userInfo = @{NSLocalizedDescriptionKey:NSLocalizedString(@"Invalid pubId/siteId/adId", nil)};
            NSError *error = [NSError errorWithDomain:kGADErrorDomain code:kGADErrorMediationDataError userInfo:userInfo];
            [self.delegate customEventBanner:self didFailAd:error];
            PMBannerAdRequest *pmBannerAdReq = [[PMBannerAdRequest alloc] initWithPublisherId:pubId siteId:siteId adId:adId];
            self.bannerAdView = [[PMBannerAdView alloc] initWithFrame:CGRectMake(0, 0, 320, 50)];
            self.bannerAdView.autoresizingMask = UIViewAutoresizingFlexibleRightMargin | UIViewAutoresizingFlexibleWidth;
            self.bannerAdView.delegate = self;
            [self.bannerAdView loadRequest: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:(PMError *)error{
        NSLog(@"PubMatic Banner Ad failed");
        NSError *err = [NSError errorWithDomain:kGADErrorDomain code:kGADErrorMediationAdapterError userInfo:error.userInfo];
        [self.delegate customEventBanner:self didFailAd:err];
  5. (Optional) Notify the delegate of user interaction events via the corresponding delegate methods:



  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.

        [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 PMCustomEventBanner) 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.