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:
- Initiate an ad call prior to page loading.
- Buyers get first look at the inventory and submit pre-bid offers.
- 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.
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:
- Rich Media (MRAID 2.0)
- Interstitial (Beta version)
PubMatic Android SDK requires the following:
- Minimum Android SDK version 4.4 (API level 19) or greater.
- Android Studio version 2.3.0 or greater.
- 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.
- Follow the instructions in Getting Started before proceeding with the following integration steps. You'll also find a useful example integration in header-bidding-sampleincluded in the SDK download bundle.
The following integration instructions assume that you have already completed the Getting Started steps, Integrate PubMatic SDK and Adding Permissions to the
AndroidManifest.xmlFile. After you have completed Getting Started, you are ready to integrate header bidding with your app using the followng steps:
- Create a header bidding request.
- Prefetch bids using
- Handle prefetched bids from
- Receive DFP app event Callbacks.
- Render the prefetched creative.
Creating a header bidding request
PMBannerImpression objects using parameters that contain information about specific ad slots like
impressionId (unique identifier),
ImpressionId: Identifies a unique ad slot/banner on the screen. You'll receive PubMatic bid(s) for requested impression id(s). This should match the impression id configured in the
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 slots on the screen named,
testAd(above the fold) and
testAd(below the fold), then you can use
SlotIndexto differentiate between the slots with matching names.
AdSizes: Array of
PMSizeobjects that lets you request an ad with different sizes.
Set interstitial flag to
true, if you are requesting an Interstitial ad, otherwise you can skip this step.
Request to prefetch bids using a
PMPrefetchRequest object with the
Activity context, initializing it with your publisher id, and the
bannerImpressions instance from step 1.
Add additional targeting information to the
prefetchRequest object such as,
ethnicity, and so on.
Prefetch bids using
PMPrefetchListener object to receive the callback of PubMatic bids:
PMErrorobject used in the
PMPrefetchManager object with the
Activity context and the
listener object created in step 1:
prefetchCreatives() from the
pmPrefetchManager object created in step 2:
Handle prefetched bids from
On Success, the Prefetch Manager responds with the callback
onBidsFetched(), returning a map of
PMBid objects. The keys for this map are the impression ids. The
PMBid object contains impression ids and price information.
PublisherAdRequest object (from DFP SDK), providing it with all the targeting information using
PublisherAdView class object, passing it the
publisherAdRequestcreated in step 2:
Receive DFP app event callback
For every winning bid, the
AppEventListener (from DFP SDK) sends a DFP
Render prefetched creative
After PubMatic has the chance to serve the ad (inside
onAppEvent), call the
loadInterstitialAd() method (match to the ad format you're using), from the
PMPrefetchManager class object. Pass it the
impressionId and the
The PubMatic ad loads and renders with the prefetched creative and also sends the impression tracker. Publishers must attach it on the parent layout.
PMInterstitialAdalso send the click tracker when the user taps/clicks on the ad.
PMPrefetchManager keeps a reference to the
PMInterstitialAd in order to release their resources on
The following example demonstrates loading a Banner ad and attaching it in place of DFP ad view:
The following example demonstrates loading an Interstitial ad:
Be sure to deallocate the
PMPrefetchManager instance before your
Activity is destroyed. It calls
destroy() on rendered
HeaderBiddingBannerHelper class is part of a Publisher's app. Use this class as a convenient way to integrate PubMatic's header bidding solution with DFP.
AdSlotInfo object for each ad slot by providing
SlotName, list of
Create a list of AdSlotInfo objects.
HeaderBiddingBannerHelper object with the Activity context and the
AdSlotInfo list created in step 2. Call
execute() from the
The following example demonstrates steps 1, 2, and 3 above:
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.
Create a new order in DFP for a In-App Header Bidding API with PubMatic as the advertiser, then add the relevant details.
Set the price and priority of the line items.
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 such as "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.
Add the In-App Header Bidding API creative provided by PubMatic to the line item you created.
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.
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.
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.
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 lin
e item for very high bids:
Line Item 58 (Covers $20 and above) Targeting: bid=20*,bid=21*,bid=22*...bid=50*) rate= $21