Index Wrapper: Bidder Integration and Best Practices


This document provides information and best practices that are key to integrating with the client-side Index Wrapper. Publishers should follow these best practices to ensure maximum optimization. These practices are designed for PubMatic and all participating bidders. 

PubMatic Bidder Integration & Quality Control Process

The following describes the steps critical to the implementation and testing of the PubMatic bidder in Index's wrapper and should be followed for the configuration of every batch of sites.

  1. Index provides a spreadsheet with adunit, divid and size information for PubMatic to complete with the corresponding name slot names.
  2. The PubMatic Operations team creates new sites and tags, uploads the slot-to-adtag mapping file internally, and provides the slot names along with the size back to Index. 

    Timelines to complete this step will vary, based on the number of sites and slots the publisher wants to launch.
  3. PubMatic will discuss the PMP strategy with the publisher to determine if the PMP line items should be created separately and prioritized above open exchange.

    Deal Level Configuration

    The dont_send_winning_deal flag will be enabled by PubMatic for publishers who do not wish to receive dealid in the response. Currently, PubMatic doesn't send the deal id in the response when the deal is PubMatic-sourced. 

  4. PubMatic will notify both Index and the publisher of the PMP setup to specifically call out the line item targeting that needs to be applied, based on step 3 above. See GAM Line Item Targeting section below for more details.
  5. Index completes the remainder of the setup for PubMatic.
  6. Index provides the code to the publisher. 
  7. The publisher places the code on a page for testing.
  8. Quality Control may be performed by all parties. The PubMatic Solutions Engineering team will verify the following:
    1. The request to PubMatic contains all mandatory parameters.
    2. All slot names are being passed properly.
    3. PubMatic-specific key values are being passed to GAM correctly.
    4. PubMatic Impression (PM) Tracker call is executing successfully when PubMatic wins the impression.
    5. Get a screenshot or list of line items being targeted to verify that key values are being set properly in GAM for both open exchange and PMP (if live).

Bidder Settings in Wrapper

The following settings affect a bidder's ability to respond, monetize and compete effectively in the wrapper setup. It is highly recommended that these suggestions are followed and items are verified to ensure that PubMatic sees all impressions without issues.

Ad Slot Mapping

PubMatic shares slot names with the publisher (step #2 in PubMatic Bidder Integration section above), which the publisher sends to Index. Ensure the following are in place:

  • PubMatic provides the slot names for all adunits and their respective sizes. The adslot array should be passed to PubMatic in the ad request with comma separated values in the format 'name@widthxsize.'
  • All slots on a page should have a mapping in PubMatic to ensure a successful bid from PubMatic. The details of adunits can be seen by using Google Force Console or by looking at the GAM calls in the Developer Tool. Any slot that PubMatic is not seeing should be reported to the publisher. If the missing ad slots are not intentionally missing, the publisher should follow up with Index to update the mapping on their end.
  • Calls to other bidders can be checked to ensure if all slots are present or missing only for PubMatic or all the bidders. 
  • If PubMatic see slots in the requests that are not mapped in the PubMatic system, use the UnMapped Slot Report to verify them.

Single Request Architecture (SRA)

  • SRA defines whether individual or single requests will be made to a partner for all the slots on the page. Keep in mind that not all partners support SRA.
  • PubMatic supports SRA and can accept a request for multiple ad slots in one ad call.
  • The wrapper should ensure that all slots are sent to PubMatic either through a single request or multiple requests (based on the implementation within the wrapper and the GAM SRA setting).


  • With 'prefetch,' a wrapper can ask for bids before the slots appear on the page. If it remains disabled, it may result in PubMatic seeing much less traffic. It is recommended to keep this enabled for PubMatic when other bidders are submitting the bid in prefetch mode.
  • Prefetch is typically enabled with publishers where the timeout threshold is strict (e.g., less than 1000 ms). 

Bid Rounding

  • A wrapper may or may not round the partner's bid by approximately two decimal places. This depends on which kind of line item targeting is in place in GAM. For example, if the line item targeting is based on wildcard characters bid=1.0*, bid=1.04* then this will match with all values between $1.0-$1.05. However, if the line item price targeting has been done on a fixed price with 0.05 granularity then the bids passed to GAM should match and the targeted 
  • Using Line Item targeting with wildcard characters ensures that all partners compete at the unmodified price they offer in real time. However, Index generally performs rounding before sending the bid to GAM. (This can be optional and will be discussed between PubMatic and the publisher.)

Bidder Randomization

  • Bidder randomization should be applied without exception. The publisher should ensure this setting is enabled by default.

Key Values

The following are PubMatic-specific key values. Verification that these are being passed properly can be done in the call to GAM from the browser.

  • Open Exchange K/V: Available when PubMatic response is from the open market.
    • For Price:  ix_pub_om =<widthxheight_price in cents>,  e.g., ix_pubm_om=300x500_110
  • PMP K/V: Available when PubMatic response is from the private market. PubMatic sends the Deal ID in the response under the ' wdeal ' parameter in the 'progKeyValueMap' object.
    • For Price:  ix_pubm_pm =<widthxheight_price in cents>, e.g., ix_pubm_on=728x90_650
    • For Deal:  ix_pubm_pmid =<widthxheight_PubMatic Deal ID>, e.g., ix_pubm_pmid=728x90_PM-VABE-3260
  • Common for both open market and PMP: This key will be used to trace back the creative that has won in GAM for rendering.
    • ix_pubm_id =<Some ID>. 

GAM Settings & Reporting

Use the guidelines below for line item targeting in GAM for both open exchange and PMP line items.

GAM Line Item Targeting

  • Line items should be ready to deliver before making the partner live in the wrapper to ensure the bids sent by the partner is being utilized.
  • PMP targeting: The PMP line items should be targeted on all possible deals and price bands for the keys  ix_pubm_pm  and  ix_pubm_pmid .
  • PMP line item prioritization: Ideally, the PMP line item priority or type should be higher than the other open exchange line items.
  • Open Exchange targeting: The open exchange line items should be targeted on all possible price bands for the key,  ix_pubm_om .
  • PMP competing at the same level with Open Market: The line items for PMP and Open Exchange would be common and line item targeting should be applied with 'OR' condition on both the keys  ix_pubm_pm ix_pub_om See screenshot below.
  • The publisher should provide a minimum of read-only GAM access to PubMatic to enable us to verify the line item targeting. If this is not possible, screenshots of the line item targeting section should be provided.

Example of Key Value Targeting:

GAM Report for Partner Performance

The following dimensions and metrics can be chosen in GAM by a publisher to create a useful partner performance report.

  • Key-values
  • Advertiser
  • Line Item
  • Rate
  • Line Item Priority
  • Cost Type
  • Line Item Type
  • Adunit
  • Creative Size (This might show as deprecated but comes as part of report)
  • Filters: Key-value contains <'ix_pubm' for PubMatic and 'ix_' for all Index k/v>


  • Total Code served count
  • Total Impressions
  • Total CPM and CPC revenue
  • Ad Server impressions
  • Ad server average eCPM
  • Ad server CPM and CPC revenue
  • AdSense Impressions
  • AdSense average eCPM
  • AdSense revenue
  • Ad Exchange impressions
  • Ad Exchange average eCPM
  • Ad Exchange revenue

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents