Biddable IO Implementation Guide

Document created by catherine.racette on Apr 6, 2017Last modified by catherine.racette on Jun 7, 2017
Version 1Show Document
  • View in full screen mode


PubMatic’s Biddable IO utilizes Real-Time Bidding (RTB) to execute Insertion Orders (IOs). Driven by the shift of brand dollars to programmatic, Biddable IO enables buyers to improve the efficacy of direct buys by utilizing real-time audience data against brand safe inventory; facilitates the relationship between one seller and one buyer by leveraging header bidding and allowing direct negotiation of various aspects of IOs, including audience, volume, and price.


Trends Driving Brand Spend to Programmatic

The Proliferation of Header Bidding

Rather than being forced to monetize biddable impressions within the sequential waterfall environment, publishers are now able to make their premium inventory available to various buyers simultaneously. The democratization of inventory access provided by header bidding integrations is leading to increased demand from buyers for quality inventory available via these new programmatic channels.


Explosive Growth of Data Availability

Programmatic advertising provides vast amounts of data, which publishers can make available to buyers via the RTB pipes made available for automated transactions. Data-driven decisioning is one of the strongest advantages of RTB.


Increasing Relevance of Attribution

Buyers cannot buy based on their data in real-time with direct buying and don't have price transparency. Through auction based channels, buyers do not have priority access to premium inventories, inventory qualities, and cannot reserve such inventory. Biddable IO is a solution to address all these issues. When brand-safe, high-quality inventory is a priority, programmatic direct channels provide a measurable, biddable environment for automated buying.

Biddable IO Removes the Need for Trade offs


Biddable IO Support OpenWrap

PubMatic Wrapper is designed to send all Biddable IO Deal IDs, as well as other Deal IDs to the ad server. All ad decisioning is made on the publisher’s ad server. OpenWrap includes PMP-G, enabling buyers to leverage the benefits of RTB channels using real-time audience data, volume and price.


All of PubMatic’s PMP-G bid responses will pass through the PubMatic Wrapper to the ad server. The highest Open Marketplace bid response will also be passed and will allow the publisher’s ad server to determine which response should be used to monetize the impression.


Partner Configuration

OpenWrap can include partners in the Wrapper for deals, however only PubMatic deals are supported for Biddable IO. 


PubMatic supports deal channel value, which indicates whether a bid is an open market bid, a PMP or PMP-G. This allows publishers operational flexibility and scalability that allows for seamless management of a Biddable IO program. (Line item setup targeting for the deal channel value is explained later in this document.) Open market bids from other exchanges continue to be enabled in the Wrapper solution.


Note: In future iterations of Biddable IO, we will be able to support deals for other partners if they provide PubMatic with their respective key-value pairs. PubMatic will then customize the Wrapper to pass through each key-value to the publisher’s ad server, which identifies the higher priority line items for these deals.

PartnerKeyDeal-Channel MapDefault Deal-Channel Value

Deal Channel Map is an extra signal that denotes the deal type. This is an important signal as it allows simplification of the ad server set up.


Operational Notes

  • OpenWrap can pass multiple bids to the ad server. This includes the highest open market bid and one Deal ID per exchange (for supported exchanges). For example, a bid from PubMatic, a bid from AppNexus and an open market bid from Index Exchange. There can be one highest open market bid and one Deal ID per exchange.
  • The Wrapper passes PMP, PREFERRED or PMPG string to the DFP.
  • The open market bid can come from PubMatic or any other exchange that may have provided the highest bid for the specific impression opportunity in consideration.
    To ensure that buyers can buy guaranteed inventory through PubMatic, regardless of open market interest from other SSPs, the PubMatic SSP will only return one response.
  • It is the publisher’s ad server that makes the final decision using the appropriate line items at the right priority level and the price point at which to monetize the impression.
  • No additional configuration is necessary for the publisher to explicitly send a PMP-G deal channel and deal id value to the ad server.

Biddable IO Deal Creation

To create a Biddable IO Deal:

  • Set up a PMP-G Deal in PubMatic UI.
  • Set up the Wrapper and test deal that details are passed.
  • Set up the Line Item Priority, Custom Targeting & Creative Code on the ad server (see below).


Ad Server Line Item Creation

Create a Line Item

  1. In DFP, click Delivery from the main navigation.
  2. Click New Order.
  3. Complete the relevant information as per the standard order creation process. Information to be entered includes start time, end time, etc. Most publisher ad operations teams are well-familiar with this step.
  4. Assign the desired priority level to this order. Standard is recommended, but Sponsorship can be created also as per the Biddable IO goal.

Line Item Priority

Refer to DFP Delivery Priority Optionsdocumentation for the most up-to-date DFP information. Details may change frequently, so the publisher should consult the DFP documentation directly to confirm the information provided below is the most current.


Biddable IO deals should be set up at the Sponsorship or Standard priority level. Each has its purpose in the ad server. Biddable IO line items should match the intended goals for which these priority tiers are intended – share of voice or absolute share of inventory.

  • A line item with Sponsorship priority enables the publisher to prioritize the deal at the highest priority, however, they can only set a share of volume as the target of the deal and not specific inventory volume.
  • A line item with Standard priority can set the goal for a specific inventory volume, but the priority will be lower. In this case, if there is a higher priority line item setup in DFP, the line item won’t be targeted.


Line ItemPriorityFeatures

Highest Priority

No impression goal; targets share of voice instead.

Too many non-delivering line items may create temporary forecasting issues.


Lower priority than sponsorship.

Impressions goal (DFP manages pacing)


To understand how forecasting accounts for key-values, refer to DFP Documentation.


Add Creative Code

  1. In DFP, click Delivery from the main navigation.
  2. Click Creatives in the left-hand navigation.
  3. Click Add Creatives.
  4. Search for and click Continue to add the advertiser whose creative is being added.
  5. Click Custom.
  6. Enter a name for the creative.
  7. Copy/Paste the following script in the creative field. This code is used to accept PubMatic’s Deal ID.
<script type='text/javascript'>
            var i = 0, w = window.self;
            while(w!== && !(w.PWT && w.PWT.displayCreative) && i<10){
                  w = window.self.parent; i++;
            try{ w.PWT.displayPMPCreative(document, '%%PATTERN:pwtdeal_pubmatic%%', []); } catch(e){}
  1. Complete other required fields.
  2. Save the creative.

Creative Display Function

This creative is specific for PubMatic; %%PATTERN:pwtdeal_pubmatic%% must be updated with the specific partner key.

Custom Targeting

An important last step in the line item setup is to complete custom targeting. This allows the ad server to action on the Deal ID and the Deal Channel Value that are passed by the Wrapper through to the ad server.

  • Publishers can include specific Deal IDs while setting up line items. These Deal IDs will be included in the custom parameter targeting as per below.
  • Publishers can also set up line items to target the deal channel type only. For this, a wild card needs to be entered after the deal channel as part of the relevant key value. When configured correctly a new Deal ID does NOT need to be entered every time a new deal needs to be activated.


This line item should have the following key value targeting:

Key: pwtdeal_pubmatic

Value: <DealChannel>*                        (If the publisher wants to target all PMP-G deals)

Value: <DealChannel> _-_<DealId>_-_* (If the publisher wants to only target specific Deal IDs)


Sample Deal Targeting Scenarios

Targeting a specific PMPG deal for PubMatic (e.g., PUBDEAL1)


The separator _-_* at the end is necessary; If it isn’t present an example such as PMPG_-_PUBDEAL1* will target all deals such as PUBDEAL123, PUBDEAL1XYZ, etc.

The wildcard match character * at the end is also mandatory as the last parameter passed after deal ID is bid ID which is used for creative rendering.

Targeting specific PMP deal for PubMatic (e.g PUBDEAL1)pwtdeal_pubmatic=PMP_-_PUBDEAL1_-_*
Targeting multiple PMPG deal for PubMatic (e.g PUBDEAL1, PUBDEAL2)pwtdeal_pubmatic=PMP_-_PUBDEAL1_-_* OR PMP_-_PUBDEAL2_-_*
Targeting all PMPG deals in one line itempwtdeal_pubmatic=PMPG_-_*
Targeting deals starting with specific string e.g all deals starting with PUBpwtdeal_pubmatic=PMPG_-_PUB*
Targeting deals coming for other supported partners (check the supported partners list & partner-key above)pwtdeal_<partner-key>=PMPG_-_PARTNERDEAL1

Note: The special combination of separator characters _-_should not be present in the actual Deal ID String

Using a Specific Deal ID

Using a Deal Channel Targeting

Common Pitfalls

  • Do not create line items at a higher priority than what it deserves.
  • Allocating lesser inventory to the line item than desired. Ad server will start throttling in this case.
  • Custom targeting with Deal ID should include proper wildcards - <Targeting including deal id>_-_*. Do not enter <Targeting including deal id>*.
  • Attach the desired creative to the right line item. The creative should have PubMatic-specific targeting as described above.
  • Targeting criteria may impact how line items are delivered. Deal ID with wildcard targeting should usually be at a lower priority than deal-specific line items.