OpenWrap – InApp Developer Guide iOS - InApp Header Bidding for DFP (1.2.2)

Document created by catherine.racette on Aug 8, 2017Last modified by catherine.racette on Oct 26, 2017
Version 17Show Document
  • View in full screen mode

(Version 1.2.2)


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.


High-Level Process Overview

  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.


The header bidding arrangement accomplishes several objectives:

  • 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 is supported



Integration of DFP SDK & DFP banner ad view


In-App Code Integration

  1. Integrating the PubMatic Sample code to Publisher Application
  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)

Integrating the PubMatic Sample Code to Publisher Application

The Publisher should refer the PubMatic's Sample Application for faster & easier integration. The 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: Used to identify unique ad slot/banner of DFP on screen, this should match with imp_id configured at step 2 in Ad Server Setup section below.

  • SlotName: A string identifier. It should be the same slot name mapped to PubMatic ad tag. Refer to the inventory mapping completed by PubMatic.

  • SlotIndex: Required when the 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 the same name.

  • AdSizes:  Array of PMSize objects that lets you request an ad with different sizes.

  1. Create a prefetch request object by specifying the 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. Upon 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 is a template that manages the PubMatic pre-fetch calls and makes ad server requests by providing PubMatic bids. This step is optional and can be skipped, particularly if a publisher would like more control over the Ad server calls (DFP ad request). Alternatively, a publisher may choose to complete this step, as HeaderBiddingBannerHelper class can make the integration easier. 


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 (PMSize) and DFPBannerView.
    AdSlotInfo * adSlot = [[AdSlotInfo alloc] initWithDFPBannerView:self.dfpView slotName:
    <SlotName> sizes:<AdSizes>];
  2. Create a list of AdSlotInfo objects. 

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 behaviour on setting refresh interval value

Value (X) in secondsBehaviour
X<=0Ad will not refresh
X > 0 & X <= 12Ad will get refreshed after every 12 seconds.
X > 12 & X <=120Ad will get refreshed after every X seconds
X > 120Ad will get refreshed after every 120 seconds

Note: To use this feature, please disable third party (e.g., DFP) refresh functionality.          

App Debugging

Header bidding code logs the request & response from the PubMatic server in debug mode. This debug log can help to see if PubMatic is providing proper bids or not. Below is sample logs from Header bidding sample application.



ATS Configuration on iOS 9.0 or later

App Transport Security (ATS) is enabled by default for apps linked against the iOS 9.0 or later. Currently, Pubmatic’s mobile header bidding solution uses HTTP end point. Thus, you need to add exceptions by configuring NSAppTransportSecurity key’s value in your app’s Info.plist file.


e.g. Add following to your Info.plist file.


For more details see ATS reference in Apple’s documentation.


PubMatic Prefetch API Parameter Details

Refer to the following properties for sending the targeting parameter values.


Table 2. PMBannerPrefetchRequest properties

S. noMethodDescription
1storeUrlURL of the app store from where a user can download this application. This URL must match the storeurl that is whitelisted in the UI.
2appDomainIndicates the domain of the mobile application

Indicates whether the mobile application is a paid version or not. Possible values are:

PMBOOLNo - Free version
PMBOOLYES - Paid version


Indicates whether the tracking URL has been wrapped or not in the creative tag.

Possible options are:



PMAWTSeparateTracker - Indicates that the tracking URL is sent separately in the response JSON as tracking_url. In this case, the tracking_url field is absent in the JSON response.

PMAWTiframeEmbeddedTracker - Indicates that the tracking_url value is wrapped in an Iframe and appended to the creative_tag.

PMAWTJSEmbeddedTracker - Indicates that the tracking_url value is wrapped in a JS tag and appended to the creative_tag.

5pmZoneIdThis parameter is used to pass a zone ID for reporting.
6ethnicityNumeric code of ethnicity
7userIncomeUser's income or income range in dollars (whole numbers). For example, inc=50000 or 50000-75000. 
8birthYearVisitor's birth year as a four-digit integer. For example, 1975.
9genderGender of the visitor. Possible values are:
PMGenderMale - Male
PMGenderFemale - Female
PMGenderOther - Others
10cityCity of the user. For example, city=New York
11zipHome zip code if the visitor is present in the U.S.; otherwise it indicates the postal code. 

Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's Online Privacy Protection Act) compliance, if the visitor's age is below 13, then such visitors should not be served targeted ads.


Possible options are:

  • PMBOOLNo - Indicates that the visitor is not COPPA-specific and can be served targeted ads.
  • PMBOOLYES - Indicates that the visitor is COPPA-specific and should be served only COPPA-compliant ads.


The United States Federal Trade Commission has written a comprehensive FAQ on complying with COPPA at

13appCategoryApplication primary category as displayed on storeurl page for the respective platform.
14keywordslist of keywords indicating the consumer's interests or intent. 
15latitudeLatitude of the device location.
16longitudeLongitude of the device location


If set, it restricts user and device targeting.


This can also be set by enabling the "Limit Ad Tracking" option in the iOS device.


If set, it uses advertisement id otherwise it uses vendor id for targeting.

This only applies if 'dnt' is set to NO.


Allows to apply the following hashing on udid param value before sending to server:
Default is PMUdidhashTypeRaw


List of IAB content categories for the overall site/application. Refer the "Table 6.1 Content Categories" in the Open RTB 2.1 / 2.2 specifications document. If the site/application falls under multiple IAB categories, you can send categories separated by comma


Note: For more details about these parameters, please refer to HTTP Parameters Details (SSP Ad Server) 


PubMatic Mapping 

Inventory mapping for PubMatic slots and ad tags must be completed in the PubMatic Admin console. Please contact your Customer Success Manager to complete this process.


Ad Server Setup on DFP

In addition to in-app code integration, DFP ad server line items need to be created with small price increments. PubMatic operations team creates these line items using an internal tool. 


The publisher must provide trafficker level access to create these line items to the email id provided by the PubMatic operations team. The publisher must inform PubMatic operations team about the granularity at which they would like these line items to be created. The details are specified in a recommended format in an excel file which is available upon request.


Trafficking the In-App Header Bidding Campaign in the Ad Server

This step is required so impressions can be allocated to PubMatic by the ad server, based on actual bid price and the recommendation from PubMatic. These are passed to the ad server using key-value pairs added to the ad server tags dynamically, as explained in the sections above.

Note: The preferred option for the PubMatic TAM team is to support the order creation in DFP. The client just needs to provide trafficker-level access. PubMatic's order insertion tool can be used to insert relevant order into DFP and create granular line items. 


Step 1: Create a new order in DFP for a In-App Header Bidding API with PubMatic as the advertiser and add the relevant details.

Step 2: Set the price and priority of the line items.

Step 3: Set targeting on the “bidstatus” value as 1 from the In-App Header Bidding API tag’s response. In addition to “bidstatus”, you can also set targeting on “bid” or “wdeal” (depending on custom key-value targeting in DFP). For more information, please refer to the Best Practices to Create Tags in the Ad Server section. 

Step 4: Add the In-App Header Bidding API creative provided by PubMatic to the line item you created.

<script type="text/javascript" src=""></script>
<script type="text/javascript">"pubmaticdm","%%PATTERN:bidid%%");

Pre-Launch Verification

Before setting traffic live, PubMatic’s Solutions Engineering team will assist the publisher’s technical and ad operations teams conduct pre-launch verification. Once verifications are complete the set up is ready to go live on a small number of sites. Post-launch, the PubMatic Operations team will ensure that the publisher is achieving the desired results and will provide consultation to ramp up the implementation.


Best Practices for Creating Line Items in the Ad Server

To control monetization through In-App Header Bidding at a granular level, you may:

  • Create multiple In-App Header Bidding line items in the ad server for each ad unit/ad size/CPM range/geo.
  • Use “bid” as the targeting attribute.
  • Place the line items at different priorities based on their pricing and relevance.

While creating line items at multiple price points, we recommend you create line items with more granular pricing where the bid density is high.


If 80% of the bids are between $0 to $3, create line items at a $0.1 granularity. For other ranges you can create line items at a higher granularity.


Sample Variations:

30 line items between $0-$3 with rate increment of $0.1

  • LineItem 1 (covers $0-$0.09) Targeting: bid=0.01*,bid=0.02*....,bid=0.09*, rate=$0.05
  • LineItem 2 (covers $0.10-$0.19) Targeting: bid=0.1*, rate=$0.15 
    and so on for next 28 line items


15 Line items between $3-$8 with rate increment of $0.30

  • LineItem 31 (covers $3.0-$3.29) Targeting: bid=3.0*,bid=3.1*,bid=3.2*, rate=$3.15
  • LineItem 32 (covers $3.30-$3.59) Targeting: bid=3.3*,bid=3.4*,bid=3.5*, rate=$3.45 
    and so on for next 13 line items


12 Line items between $9-$20 with rate increment of $1.0

  • LineItem 46 (covers $9.0-$9.99) Targeting: bid=9.*, rate=$9.5
  • LineItem 47 (covers $10.0-$10.99) Targeting: bid=10.*, rate=$3.45 
    and so on for next 10 line items


A final high- priority line item for very high bids

  • Line Item 58 (Covers $20 and above) Targeting: bid=20*,bid=21*,bid=22*...... bid=50*) rate= $21