Page tree

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.

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
  • Rich Media (MRAID 2.0)
  • Interstitial (Beta version)


PubMatic Android SDK requires the following:

  1. Minimum Android SDK version 4.4 (API level 19) or greater.
  2. Android Studio version 2.3.0 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 header-bidding-sampleincluded in the SDK download bundle.

Integration Steps

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:

  1. Create a header bidding request.
  2. Prefetch bids using PMPrefetchManager.
  3. Handle prefetched bids from PMPrefetchManager.
  4. Receive DFP app event Callbacks.
  5. Render the prefetched creative.
  6. Deallocate PMPrefetchManager resources.
  7. Use HeaderBiddingBannerHelper (Optional).

Creating a header bidding request

Step 1

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

PMBannerImpression Object
PMBannerImpression bannerImpression = new PMBannerImpression( <ImpressionId>, <SlotName>, <AdSizes>, <SlotIndex> );
  • 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 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 slots on the screen named, testAd (above the fold) and testAd(below the fold), then you can use SlotIndex to differentiate between the slots with matching names.

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

Step 2

Set interstitial flag to true, if you are requesting an Interstitial ad, otherwise you can skip this step. 

Set The Interstitial Flag

Step 3

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. 

PMPrefetchRequest adRequest = PMPrefetchRequest.initHBRequestForImpression(<PubId>, bannerImpressions);

Step 4

Add additional targeting information to the prefetchRequest object such as, storeURLappDomaingenderethnicity, and so on.

For more targeting parameters see, Passing Targeting Information.

Prefetch bids using PMPrefetchManager

Step 1

Create a PMPrefetchListener object to receive the callback of PubMatic bids: 

Create PMPrefetchListener Object
PMPrefetchManager.PMPrefetchListener listener = new PMPrefetchManager.PMPrefetchListener () {
            public void onBidsFetched(Map<String, PMBid> hbResponse) {
                // Header bidding completed. Now send the custom data to DFP.

            public void onBidsFailed(PMError error) {
                // Get on with requesting DFP for ads without HB data.
See PubMatic SDK Error Codes for a detailed description of the PMError object used in the onBidsFailed() callback.

Step 2

Create a PMPrefetchManager object with the Activity context and the listener object created in step 1: 

Create PMPrefetchManager Object
PMPrefetchManager pmPrefetchManager = new PMPrefetchManager(<Context>, <PMPrefetchListener>);‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Step 3

Call prefetchCreatives() from the pmPrefetchManager object created in step 2: 

Call PrefetchCreatives() From PMPrefetchManager

Handle prefetched bids from PMPrefetchManager

Step 1

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.

Step 2

Create a PublisherAdRequest object (from DFP SDK), providing it with all the targeting information using addCustomTargeting

Create PublisherAdRequest Object
// Fetch the winning bid details for the impressionId & send to DFP
    PMBid pubResponse = hBResponse.get(<impressionId>);
    if (pubResponse != null) {

        PublisherAdRequest.Builder requestBuilder = new PublisherAdRequest.Builder();

            requestBuilder.addCustomTargeting(WDEAL_ID, pubResponse.getDealId());

            requestBuilder.addCustomTargeting(BID_ID, pubResponse.getImpressionId());

        String price = String.valueOf(pubResponse.getPrice());

        if(!TextUtils.isEmpty(price)) {
            double bidPrice = Double.valueOf(price);

            if(bidPrice > 0.0d) {
                requestBuilder.addCustomTargeting(BID, price);
                requestBuilder.addCustomTargeting(BID_STATUS, "1");
            } else {
                requestBuilder.addCustomTargeting(BID_STATUS, "0");

        adRequest =;

    } else {
        adRequest = new PublisherAdRequest.Builder().build();

Step 3

Call loadAd() from PublisherAdView class object, passing it the publisherAdRequestcreated in step 2: 

Call LoadAd() From PublisherAdView Object

Receive DFP app event callback

For every winning bid, the AppEventListener (from DFP SDK) sends a DFP onAppEvent()callback: 

onAppEvent Callback
onAppEvent(event, impressionId) {
    //Check if event is for PubMatic then Render the Prefetched creative

Render prefetched creative

After PubMatic has the chance to serve the ad (inside onAppEvent), call the loadBannerAd()or loadInterstitialAd() method (match to the ad format you're using), from the PMPrefetchManager class object. Pass it the impressionId and the PMBannerAdView or PMInterstitialAd instance: 

PMPrefetchManager Load Calls
pmPrefetchManager.loadBannerAd(<impressionId>, <PMBannerAdView>);


pmPrefetchManager.loadInterstitialAd(<impressionId>, <PMInterstitialAd>);‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The PubMatic ad loads and renders with the prefetched creative and also sends the impression tracker. Publishers must attach it on the parent layout. PMBannerAdView/PMInterstitialAdalso send the click tracker when the user taps/clicks on the ad. PMPrefetchManager keeps a reference to the PMBannerAdView/PMInterstitialAd in order to release their resources on destroy().

The following example demonstrates loading a Banner ad and attaching it in place of DFP ad view: 

Load and Attach Banner Ad Example
// Pass activity context in PMBannerAdView
PMBannerAdView adView = new PMBannerAdView(<Context>);

ViewGroup.LayoutParams layoutParams = new ViewGroup.LayoutParams(adSlotInfo.adView.getLayoutParams());
layoutParams.width = adSlotInfo.adView.getMeasuredWidth();
layoutParams.height = adSlotInfo.adView.getMeasuredHeight();

// Display PubMatic Cached Ad
pmPrefetchManager.loadBannerAd(impressionId, adView);

// Replace view with pubmatic Adview.
ViewGroup parent = (ViewGroup) adSlotInfo.adView.getParent();
if (parent != null) {
    parent.addView(adView, adSlotInfo.adView.getLayoutParams());

The following example demonstrates loading an Interstitial ad: 

Load and Show Interstitial Ad Example
// Pass activity context in PMInterstitialAd
PMInterstitialAd adView = new PMInterstitialAd(<Context>);

// Load PubMatic prefetched Ad
pmPrefetchManager.loadInterstitialAd(impressionId, adView);

// Once ad loads, show Interstitial ad;‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Deallocate PMPrefetchManager resources

Be sure to deallocate the PMPrefetchManager instance before your Activity is destroyed. It calls destroy() on rendered PMBannerAdView and PMInterstitialAd

Deallocate PMPrefetchManager Instance

Using HeaderBiddingBannerHelper (Optional)

The 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.

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

Step 1

Create an AdSlotInfo object for each ad slot by providing SlotName, list of AdSizes, and PublisherAdView

Create AdSlotInfo Objects
HeaderBiddingBannerHelper.AdSlotInfo adSlotInfo = new HeaderBiddingBannerHelper.AdSlotInfo(<SlotName>, <List[AdSizes]>, <PublisherAdView>);‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Step 2

Create a list of AdSlotInfo objects.

Step 3

Create a HeaderBiddingBannerHelper object with the Activity context and the AdSlotInfo list created in step 2. Call execute() from the HeaderBiddingBannerHelper object.

Combined Example

The following example demonstrates steps 1, 2, and 3 above: 

Combined Example
List<PMAdSize>   adSizes1 = new ArrayList<>(1);
adSizes1.add(new PMAdSize(320, 50));
HeaderBiddingBannerHelper.AdSlotInfo adSlotInfo1 = new HeaderBiddingBannerHelper.AdSlotInfo(<SlotName>, <List[AdSizes]>, <PublisherAdView>);

List<PMAdSize>   adSizes2 = new ArrayList<>(1);
adSizes2.add(new PMAdSize(320, 50));
HeaderBiddingBannerHelper.AdSlotInfo adSlotInfo2 = new HeaderBiddingBannerHelper.AdSlotInfo(<SlotName>, <List[AdSizes]>, <PublisherAdView>);

adSlotInfoList = new ArrayList<>(2);

// For Adapter
HeaderBiddingBannerHelper hbBannerHelper = new HeaderBiddingBannerHelper(<Context>, adSlotInfoList);

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.

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 bidstatusyou 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.

Step 4

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

Add In-App Header Bidding API
<script type="text/javascript" src=""></script>
<script type="text/javascript">"pubmaticdm","%%PATTERN:bidid%%");

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.


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 lin e item for very high bids:

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

⇧ Top