Header Bidding With DFP

Document created by david.simerly on Oct 20, 2017Last modified by david.simerly on Apr 3, 2018
Version 30Show Document
  • View in full screen mode

PubMatic SDKs 

PubMatic iOS SDK 

Getting Started

Integrating Banner Ads

Integrating Interstitial Ads

Rich Media (MRAID 2.0) Support

Integrating Native Ads

➤  Header Bidding With DFP

Passing Targeting Information

SDK Debugging


PubMatic iOS SDK Reference 

In-app header bidding lets publishers allocate ad inventory using a technology and methodology that bypasses inefficiencies that prevent 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. At a high level this is a three-step process:

 

  1. Initiate an ad call prior to page loading.
  2. Buyers get first look at the inventory and submit pre-bid offers.
  3. The pre-bid offer becomes the bid floor pricing for the ad server call, which checks if any other buyers in the same priority tier can offer higher. As a result, inventory gets allocated to the highest yielding buyer while respecting other publisher controls that may have been set up on the ad server.

 

Header bidding primarily benefits publishers who use third party SDKs (for example, DFP), to manage their ads. However, DFP doesn't allow publishers to effectively include programmatic buyers that compete against AdX and direct deals, so publishers are limited in the buyers they can include.

 

When a page in the publisher's app loads, the code queries PubMatic for bids before the ad server's direct sales. Bidding is essentially simultaneous instead of sequential, and focuses on all available impressions, not just those available after direct sales.

 

The diagram below shows how PubMatic SDK header bidder integrates with a publisher's app.

 

image

 

Publishers also have the option to allow the winning bid to compete with prices available from the direct-sold ads. This header bidding arrangement accomplishes several things:

 

  • All demand sources are bidding at the same time, which replaces a preferential waterfall-order of buyers.
  • Advertisers have a chance to buy the best ad inventory.
  • Stats show that publishers gain as much as a 50% increase in CPMs.

 

Supported Ad Formats

Header bidding with DFP supports the following ad formats:

 

  • Banner
  • Interstitial
  • Rich Media (MRAID 2.0)

 

Prerequisites

PubMatic iOS SDK requires the following:

 

  1. iOS 9 or greater.
  2. Xcode 8 or greater.
  3. PubMatic ad tag information (Publisher ID, Site ID, and Ad ID). You can get these values from the PubMatic platform; contact your PubMatic Account Manager for more information.
  4. DFP ad unit and DFP SDK.

 

Follow the instructions in Getting Started before proceeding with the following integration steps. You'll also find a useful example integration in HeaderBiddingSampleincluded in the SDK download bundle.  

 

If you are using the Cocoapods integration method, choose one of the following code segments to add all ad formats, or to add selected ad formats to your Podfile for header bidding setup:

 

Cocoapods Header Bidding Setup for Banner and Interstitial Ads:

 

platform :ios, '9.0'
target "SampleApp" do
pod 'PubMaticSDK/HB'
end

 

Cocoapods Header Bidding Setup for Individual Ad Formats:

Add one or both of the options below to your Podfile to enable your preferred ad format(s):

 

# Integrate only Banner header bidding
pod 'PubMaticSDK/HB/Banner'
# Integrate only Interstitial header bidding
pod 'PubMaticSDK/HB/Interstitial'

 

Once you've downloaded and installed the PubMatic iOS SDK with the header bidding additions described above, use the following sections to implement and configure header bidding in Banner and interstitial ads.

 

Display Banner Ad

The following sections describe how to setup header bidding for Banner ads. The process involves:

 

  1. Creating a Header Bidding Request
  2. Prefetching Bids Using PMPrefetchManager
  3. Handling Prefetched Bids from PMPrefetchManager
  4. Requesting Ad From DFP With The Prefetched Bid Information
  5. Receiving a DFP App Event Callback
  6. Rendering the Prefetched Creative

 

Creating a Header Bidding Request

Step 1

Create PMBannerImpression objects using parameters that contain information about specific ad slots like impressionId (unique identifier), slotName, slotIndex, and sizeArray:

 

PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<#ImpressionId#>
slotName:<#SlotName#> slotIndex:<#SlotIndex#> sizeArray:<#AdSizes#>];

 

  • ImpressionId: Identifies a unique ad slot/banner on the screen. You'll receive PubMatic bid(s) for requested impression id(s) (bid.impId). This should match the impression id configured in the PMBannerImpression object.

  • SlotName: A string identifier. It should be the same slot name mapped to a PubMatic ad tag.

  • SlotIndex: Required when the same slot name is used multiple times on the screen. For example, if there are two slot names on the screen, testAd (above the fold) and testAd(below the fold), then you can use SlotIndex to differentiate between the slots with same name.

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

 

Step 2

Request prefetched bids with a PMPrefetchRequest object by specifying publisher id and impression (from step 1).

Example of creating ad request and setting basic parameters:

 

    PMPrefetchRequest * prefetchRequest = [[PMPrefetchRequest alloc] 
    initForPrefetchWithPublisherId:<#PublisherId#> impressionArray:<#impression#>];
    [prefetchAdRequest setKeywords:@"entertainment,sports"];
    [prefetchAdRequest setEthnicity:PMEthnicityAsianAmerican];
    [prefetchAdRequest setPaid:NO];
    [prefetchAdRequest setDma:@"734"];
    [prefetchAdRequest setCoppa:YES];
    [prefetchAdRequest setIABCategory:@"IAB1-1,IAB1-7"];

 

Step 3

Add additional targeting information to the prefetchRequest object such as, storeURL, appDomain, gender, ethnicity, and so on:

 

prefetchRequest.storeURL = @"http://www.pubmatic.com";
prefetchRequest.appDomain = @"www.pubmatic.com";
prefetchRequest.ethnicity = PMEthnicityAsianAmerican;

 

For more targeting parameters, see Passing Targeting Information.

                 

 

Prefetching Bids Using PMPrefetchManager

Step 1

Create a PMPrefetchManager object and set the delegate to your PMPrefetchDelegate object in your view controller object:

 

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

 

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

 

Step 2

Adopt the PMPrefetchDelegate and implement the delegate methods:

 

- (void)prefetchManager:didReceiveBids:
- (void)prefetchManager:didFailWithError:

 

See PubMatic SDK Error Codes for a detailed description of the PMError object used in the prefetchManager:didFailWithError: callback.

 

Step 3

Call prefetchCreativesForRequest: from the PMPrefetchManager object created in step 1:

 

    [prefetchManager prefetchCreativesForRequest:prefetchRequest];

 

Handling Prefetched Bids from PMPrefetchManager

 

  • On success, the PMPrefetchManager responds with the delegate callback - (void)prefetchManager:didReceiveBids:, returning a dictionary of PMBid objects. The keys for this dictionary are the impression ids.
  • The PMBid object contains impression id, status, and price information.

    For example:

 

  • - (void)prefetchManager:(PMPrefetchManager *)prefetchManager didReceiveBids:(NSDictionary *)bids{
    //to get bid for an impressionId.
    PMBid *bid = bids[impressionId];
    }

 

Requesting Ad From DFP With The Prefetched Bid Information

 

  • Create a DFPRequest object and provide it with target 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]];

    dealId is used for PMP deals.
  • Call loadRequest: from DFPBannerView with the dfpRequest created in step 1.

    [dfpView loadRequest:dfpRequest];

Receiving a DFP App Event Callback

The app receives a DFP app event for every winning bid.

 

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

 

Where name is the app event name and info is the impressionId won by the header bid.

 

Rendering Prefetched Creative

Create a PMBannerAdView, as you would for a simple Banner ad, with the required frame. Call the loadAdForImpressionId:withRenderer: method from the PMPrefetchManager object and pass the impressionId and created PMBannerAdView object as a renderer.

 

PMBannerAdView *pubMaticBannerAd = [[PMBannerAdView alloc] initWithFrame:<#AdFrame#>];
[prefetchManager loadAdForImpressionId:info withRenderer:pubMaticBannerAd];

 

Add this Banner view to your ad container or to the appropriate view where the Banner ad should display.

 

[<#AdContainer#> addSubview:pubMaticBannerAd];

 

PMBannerAdView renders the Banner ad using PubMatic iOS SDK's rendering functionality.

 

Refresh functionality is currently not available in SDK header bidding. Thus, setting an update interval using updateInterval property from PMBannerAdView won't have any effect.

                       

 

Using HeaderBiddingBannerHelper (Optional)

The HeaderBiddingBannerHelper class belongs in the Publisher's app. This class provides a convenient way to integrate PubMatic's header bidding solution with DFP. It creates impression objects for your ad slots, fetches bids from PubMatic, and renders the Banner ads if a bid wins.

 

  1. Create a BannerAdSlotInfo object for each ad slot by providing a slot name , list of ad sizes, and DFPBannerView:

    BannerAdSlotInfo * adSlot = [[BannerAdSlotInfo alloc] initWithDFPBannerView:self.dfpView slotName:<#SlotName#> sizes:<#AdSizes#>];
  2. Create a list of BannerAdSlotInfo objects.

  3. Create a HeaderBiddingBannerHelper object with the ad slot list created in step 2 and call execute.

    HeaderBiddingBannerHelper *helper = [[HeaderBiddingBannerHelper alloc] initWithAdSlotInfo:<#AdSlotInfoArray#>; 
    [helper execute];

 

Interstitial Ads

The following sections describe how to setup header bidding for interstitial ads. The process involves:

 

  1. Creating a Header Bidding Request
  2. Prefetching Bids Using PMPrefetchManager
  3. Handling Prefetched Bids from PMPrefetchManager
  4. Requesting Ad From DFP With The Prefetched Bid Information
  5. Receiving a DFP App Event Callback
  6. Rendering the Prefetched Creative

 

Creating a Header Bidding Request

Step 1

Create Impression objects using PMBannerImpression class in the same fashion as step 1 of Display Banner Ad above. Set isInterstitial flag to YES in the impression object to signify it as an interstitial impression:

 

PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<#ImpressionId#> slotName:<#SlotName#> slotIndex:<#SlotIndex#> sizes:<#AdSizes#>, nil];
impression.isInterstitial = YES;

 

Step 2

Request prefetched bids with a prefetchRequest object with the PublisherId and impression from step 1:

 

PMPrefetchRequest *prefetchRequest = [[PMPrefetchRequest alloc] initForPrefetchWithPublisherId:<#PublisherId#> impressions:<#impression#>, nil];

 

Step 3

Specify additional targeting information in the PMPrefetchRequest object such as, store URL, app domain, gender, ethnicity and much more:

 

prefetchRequest.storeURL = @"http://www.pubmatic.com";
prefetchRequest.appDomain = @"www.pubmatic.com";
prefetchRequest.ethnicity = PMEthnicityAsianAmerican;

 

Prefetching Bids Using PMPrefetchManager

See Display Banner Ads > Prefetching Bids Using PMPrefetchManager.

 

Handling Prefetched Bids From PMPrefetchManager

See Display Banner Ads > Handling Prefetched Bids From PMPrefetchManager.

 

Requesting DFP Ad With Prefetched Bid Information

Create a DFPRequest object and provide it targeting information using setCustomTargeting:. Use the corresponding PMBid object received in prefetchManager:didreceiveBids: delegate callback (See Display Banner Ads > Requesting Ad From DFP With The Prefetched Bid Information).

 

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]];

 

dealId is used for PMP deals.

 

Call loadRequest: from DFPInterstitial object with the dfpRequest created in step 1.

 

[dfpInterstitial loadRequest:dfpRequest];

 

Receiving a DFP App Event Callback

The app receives a DFP app event for every winning bid:

 

- (void)interstitial:(GADInterstitial *)interstitial didReceiveAppEvent:(NSString *)name withInfo:(NSString *)info

 

Where name is the app event name and info is the impressionId won by the header bid.

 

Rendering the Prefetched Creative

Create a PMInterstitialAd, as you would for a simple Interstitial ad.

 

Call the loadAdForImpressionId:withRenderer: method from the PMPrefetchManager object and pass the impressionId and created PMInterstitialAd object as the renderer:

 

PMInterstitialAd *pmInterstitial = [[PMInterstitialAd alloc] initInterstitial];
[pmInterstitial setDelegate:self];
[prefetchManager loadAdForImpressionId:info withRenderer:pmInterstitial];

 

PMInterstitialAd loads the interstitial ad using PubMation iOS SDK's rendering functionality. To show this interstitial ad, call show or showForDuration: from the PMInterstitialAdobject you just created:

 

[pmInterstitial show];

 

Ad Server Set-Up

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

 

To create these line items publishers must email trafficker level access to the address provided by the PubMatic Operations team. Publishers must also instruct the PubMatic Operations team about the granularity with which to create the line items. Publishers can provide these details in a pre-formatted Excel template which PubMatic Operations provides upon request.

 

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

This required step in DFP allocates impressions from the ad server to PubMatic, based on the actual bid price and PubMatic's recommendation. PubMatic passes these line items to the ad server as key-value pairs that are added to the ad server tags dynamically, as explained in Ad Server Set-Up above.

 

The preferred option for the PubMatic Operations team is to support the order creation in DFP. See the previous section, Ad Server Set-Up.

 

Step 1

Create a new order in DFP for a In-App Header Bidding API with PubMatic as the advertiser, then add the relevant details.

 

image

 

Step 2

Set the price and priority of the line items.

 

image

 

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 use Add key to target other keys like “bid” or “wdeal” (depending on custom key-value targeting in DFP). For more information, see the Best Practices for Creating Line Items in the Ad Server section below.

 

image

 

Step 4

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

 

<script type="text/javascript" src="https://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
<script type="text/javascript">
admob.events.dispatchAppEvent("pubmaticdm","%%PATTERN:bidid%%");
</script>

 

Pre-Launch Verification

Before allowing live traffic, PubMatic's solution engineering team, and the publisher's technical and ad operations team, will work together to conduct the pre-launch verification. Once these verifications are completed the setup is ready to go live on a handful of sites. Post-launch, PubMatic operations team will help ensure that the publisher is achieving 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 can:

 

  • Create multiple In-App Header Bidding line items in the ad server for each ad unit, ad size, CPM range, and 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, PubMatic recommends that you create line items with more granular pricing where the bid density is high.

 

Examples:

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 with greater granularity.

 

Variations on how that might look:

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

 

Attachments

    Outcomes