OpenWrap – InApp Developer Guide  iOS - InApp Header Bidding   for DFP

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

(Version 1.2.1)


In-App Header Bidding allows publishers to allocate ad inventory using a technology and methodology that bypasses inefficiencies that have kept apps from finding the best prices.

Header bidding is the process of sending out an initial ad call to one or more buyers to solicit an exact price for inclusion in the ad server’s inventory allocation process. At a high level this is a 3-step process:

  1. The prefetch/header bidding ad call needs to be initiated before requesting ad from Primary SDK.
  2. Buyers get first look at the inventory and submit a pre-bid price.
  3. This pre-bid price then becomes the bid floor for the ad server call, which checks if any other buyers in the same priority tier can beat it. As a result, inventory gets allocated to the highest yielding buyer while respecting other publisher controls that may have been set up in the ad server.

Header bidding primarily benefits publishers who use third party SDKs (e.g., DFP) to manage their ads. However, DFP doesn’t allow publishers to effectively pull in programmatic buyers that compete against AdX and direct deals, so publishers are limited as to which buyers they can utilize.


When a page in the publisher's app is loaded, the code reaches out to PubMatic for bids before the ad server’s direct sales are called. Bidding is essentially simultaneous instead of sequential, and focuses on all available impressions, not just ones available after direct sales.


The diagram below shows how PubMatic non-SDK header bidder integrates with publisher’s app.

If desired, publishers can also allow the winning bid to compete with prices available from the direct-sold ads.

  • This header bidding arrangement accomplishes several things: All the demand sources are bidding at the same time, which replaces waterfall’s preferential ordering of buyers.
  • Advertisers have a chance at obtaining the best ad inventory.
  • Stats have shown publisher gains as high as 50 percent in CPMs.

Supported Ad Format

  • Simple Banner


Integration of DFP SDK & DFP banner ad view

In-App Code Integration

  1. Integrate the PubMatic Sample code to Publisher App
  2. Creating a Header Bidding Request
  3. Prefetching bids using PMPrefetchManager
  4. Receiving a DFP App Event Callback
  5. Rendering Prefetched Creative
  6. Using HeaderBiddingBannerHelper(Optional)
  7. Setting Refresh Interval (Optional)

Integrate the PubMatic Sample Code to Publisher App

To Publisher can refer the PubMatic's Sample application for faster & easier integration. Highlighted 'Headerbidding' folder need to be copied to Publisher's iOS application.

Creating a Header Bidding Request

  1. Import PMPrefetchManager file as shown below.
    #import "PMPrefetchManager.h"


  1. Create Impression objects that contain information about specific ad slots like impressionId (Unique identifier), slot name, sizes and slot index. It is required to make an ad request to PubMatic against impression objects.

    PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<ImpressionId> 
    slotName:<slotName> slotIndex:<SlotIndex> sizes:<AdSizes>];
  • ImpressionId: It is used to identify unique ad slot/banner of mopub on screen, this should match with imp_id configured at step 2 in Ad Server Set-Up at Mopub section below
  • SlotName: It is a string identifier. It should be the same slot name mapped to PubMatic ad tag. Please refer mapping in xls sheet in section PubMatic side set-up.
  • SlotIndex: It is required when same slot name is used multiple times on the screen. If there are two slot name on the screen, testAd (Above the fold) and testAd (Below the fold), then slotindex can be used to differentiate between slots with same name.
  • AdSizes: Different add sizes can be provided for requesting Ad with different sizes

  1. Create a prefetch request object by specifying publisher id and impressions, from step 1, to request prefetched bids. It is required to make an ad request to PubMatic against impression objects.

    Sample code for creating ad request & setting some basic parameters: 
    PMBannerPrefetchRequest * prefetchAdRequest = [[PMBannerPrefetchRequest alloc] 
    initForPrefetchWithPublisherId:<PublisherId> impressionArray:<impressions>];

    [prefetchAdRequest setAwt:PMAWTSeparateTracker];
    [prefetchAdRequest setKeywords:@"entertainment,sports"];
    [prefetchAdRequest setEthnicity:PMEthnicityAsianAmerican];
    [prefetchAdRequest setDnt:NO];
    [prefetchAdRequest setPaid:NO];
    [prefetchAdRequest setDma:@"734"];
    [prefetchAdRequest setCoppa:YES];
    [prefetchAdRequest setIABCategory:@"IAB1-1,IAB1-7"];
    <impressions> :Array of PMBannerImpression objects created in step 2

For additional parameter details, please refer to Table 2 in the Parameter details section.

  1. You can also specify additional targeting information on PMBannerPrefetchRequest object such as store URL, app domain, gender, ethnicity and much more.

Prefetching Bids Using PMPrefetchManager

  1. Create PMPrefetchManager object
    PMPrefetchManager *prefetchManager = [[PMPrefetchManager alloc] init]; 
    prefetchManager.delegate = self;

Set a network timeout (In seconds) using maxNetworkTimeout property of PMPrefetchManager. Default, network timeout is 3 seconds

  1. Adopt the PMPrefetchDelegate and implement the delegate methods -
- (void)prefetchManager:didReceiveBids: 
- (void)prefetchManager:didFailWithError:


  1. Call prefetchCreativesForRequest: on PMPrefetchManager object created in step 1
    [prefetchManager prefetchCreativesForRequest:prefetchAdRequest];


Handling Prefetched Bids from PMPrefetchManager

  1. On success, the PMPrefetchManager will respond with delegate callback - (void)prefetchManager:didReceiveBids: with a map of PMBid objects.

    The keys for this map will be the impression ids. The PMBid object contains impression id, status and price information.
- (void)prefetchManager:(PMPrefetchManager *)prefetchManager didReceiveBids:(NSDictionary *)bids 
//get bid for impressionId.
PMBid *bid = bids[impressionId];

Calling DFP ad with pre-fetched bid information. Please note prefetchManager: didReceiveBids: & prefetchManager:didFailWithError are called on secondaray thread to do UI work from these callbacks dispatch it on main queue.

  1. Create a DFPRequest object, providing it with all the targeting information using setCustomTargeting:
DFPRequest *dfpRequest = [[DFPRequest alloc] init]; 
[dfpRequest setCustomTargeting:[NSDictionary dictionaryWithObjectsAndKeys:bid.impId, @"bidid",[NSString stringWithFormat:@"%d", bid.status.intValue], @"bidstatus", [NSString stringWithFormat:@"%f", bid.price], @"bid",bid.dealId,@”wdeal
, nil]];

Note: dealId is used for PMP deals. & bid price is rounded till single decimal digit. 

  1. Call loadRequest on Main thread: on DFPBannerView with the dfpRequest created in step 1.


dispatch_async(dispatch_get_main_queue(), ^{ 
[dfpView loadRequest:dfpRequest];

Receiving a DFP App Event Callback 

For every winning bid, a DFP app event is received 

- (void)adView:(DFPBannerView *)banner 
didReceiveAppEvent:(NSString *)name
withInfo:(NSString *)info

...where, name is the app event name and info is the impressionId for which the header bid has won.

Rendering Prefetched Creative

Call renderPubMaticAdWithImpressionId:forAdView: method on PMPrefetchManager passing the impressionId and dfpView. This method will render creative & fire impression trackers.

[self.prefetchManager renderPubMaticAdWithImpressionId:info forAdView: dfpView]; 

Using HeaderBiddingBannerHelper (Optional)

The HeaderBiddingBannerHelper class will be a part of Publisher's app. This class can be used as a convenient way to integrate PubMatic's header bidding solution with DFP.


Customize this class to integrate any other header bidding partner in addition to PubMatic.

  1. Create a AdSlotInfo object for each ad slot by providing slot name , list of ad sizes and DFPBannerView.
    AdSlotInfo * adSlot = [[AdSlotInfo alloc] initWithDFPBannerView:self.dfpView slotName:
    <SlotName> sizes:<AdSizes>];
  2. Create a list of AdSlotInfo objects. 
  3. Create an object of HeaderBiddingBannerHelper with the ad slot list created in step 2 and call execute.

    HeaderBiddingBannerHelper *helper = [[HeaderBiddingBannerHelper alloc] 
    initWithAdSlotInfo:@[adSlot1, adSlot2]];

    [self.helper execute];

    Setting Refresh Interval (Optional)

    This solution provides an optional feature to auto refresh the banner ad after a specified interval.

    The default value for refresh interval is 0 seconds, i.e., by default auto refresh feature is disabled. The publisher can set an appropriate refresh interval using the refreshInterval property of PMPrefetchManager. Expected value should be in range of 12 to 120.

    Table 1. Ad refresh behavior on setting refresh interval value: