Publisher APIs

Expand all   Collapse all

Prioritizing deals for Ad Pods

Overview

These instructions guide you through how to set up an OpenWrap CTV request to enable Deal Prioritization.

Request Parameters

Parameter

Type

Description

Default value

supportdeals


integer

Request-level parameter that indicates whether OpenWrap should prioritize a deal based on the deal tiers passed in the request. Values are:

true = OpenWrap will prioritize deals based on the deal tiers passed in the request.

false = OpenWrap will not consider any deals based on priority.

JSON field = req.ext.wrapper.supportdeals

false

dealtier

object

An impression-level parameter that specifies bidder specific tier information to be used by OpenWrap in determining if deal bid is satisfying the bidder's deal tier.

dealtier has two properties:

mindealtier: The minimum deal priority that a deal bid must have to satisfy the deal tier. It must be great than 0. The higher the value, the higher the priority.

prefix: Bidder-specific prefix to be used while forming pwtpb_cat_dur when deal bid satisfies the tier.

dealtier object hierarchy:
JSON field = imp[<INDEX>].ext.bidder[<BIDDERNAME>].dealtier

includebrandcategory

integer

Only for publishers using GAM as the Primary Ad Server.

Request-level parameter that indicates whether the brand category is included in the targeting key.

0 = Indicates bid category is not expected in pwtpb_cat_dur. For example, pwtpb_cat_dur = 10.00_5s

1 = Indicates bid category returned in bid response (by corresponding bidder) is expected. Typically it would be IAB category. For Example, pwtpb_cat_dur = 10.00_IAB-17_5s

2 = Indicates Primary Ad Server defined category (Equivalent of BID IAB Category) is expected. For Example, pwtpb_cat_dur = 10.00_Sports_5s

        • It performs category translation from Bid Category to equivalent Category defined by Primary Ad Server

        • Today OpenWrap only holds the category mapping for DFP as primary ad server. We determine your Primary Ad Server from the Profile ID passed in the request

JSON field = req.ext.wrapper.includebrandcategory

0

Setting up deal prioritization 

This section provides steps for setting up deal prioritization without a primary ad server ways:

  • Without a primary ad server
  • With a primary ad server

Set up without a primary ad server

Use this set up method if you want to prioritize deals without a primary ad server.

Endpoints:

/video/openrtbReturns ad pod response in OpenRTB Format.
/video/vastReturns ad pod response in VAST XML Format.
See OpenWrap CTV Video API Specification for more information.


Pass supportdeals = true in the request-level wrapper extension object of the OpenWrap Ad Pod request, as follows:

POST request 
{
    "imp": [],
    "ext": {
        "wrapper": {
            "supportdeals": true
        }
    }
}
GET request 
/video/openrtb?req.ext.wrapper.supportdeals=true
/video/vast?req.ext.wrapper.supportdeals=true


Pass the dealtier information in the impression-level bidder extension of the OpenWrap Ad Pod request, as follows:  

  1. Replace <BIDDER_PREFIX> with a string value bidder-specific prefix required for deal tiering.
  2. Replace <MINIMUM_REQUIRED_DEAL_PRIORITY> with an integer value greater than 0.
POST request 
{
    "imp": [{
        "ext": {
            "bidder": {
                "bidder1": {
                    "dealtier": {
                        "prefix": "<BIDDER_PREFIX>",
                        "mindealtier": <MINIMUM_REQUIRED_DEAL_PRIORITY>
                    }
                },
                "bidder2": {
                    "dealtier": {
                        "prefix": "<BIDDER_PREFIX>",
                        "mindealtier": <MINIMUM_REQUIRED_DEAL_PRIORITY>
                    }
                }
            }
        }
    }]
}
GET request 
imp[<INDEX>].ext.bidder=encodeURI('{"bidder1":{"dealtier":{"prefix":"<BIDDER_1_PREFIX>","mindealtier":<MINIMUM_REQUIRED_DEAL_PRIORITY> }},"bidder2":{"dealtier":{"prefix":"<BIDDER_2_PREFIX>","mindealtier":<MINIMUM_REQUIRED_DEAL_PRIORITY>}}}')


// Output - %7B%22bidder1%22:%7B%22dealtier%22:%7B%22prefix%22:%22%3CBIDDER_1_PREFIX%3E%22,%22mindealtier%22:%3CMINIMUM_REQUIRED_DEAL_PRIORITY%3E%20%7D%7D,%22bidder2%22:%7B%22dealtier%22:%7B%22prefix%22:%22%3CBIDDER_2_PREFIX%3E%22,%22mindealtier%22:%3CMINIMUM_REQUIRED_DEAL_PRIORITY%3E%7D%7D%7D


(Optional) In this sample, we used includebrandcategory to include a bid category (1 = IAB bid category) in the request-level wrapper extension object of the OpenWrap Ad Pod request:

POST request 
{
    "imp": [],
    "ext": {
        "wrapper": {
            "includebrandcategory": 1
        }
    }
}
GET request 
/video/openrtb?req.ext.wrapper.includebrandcategory=1
/video/vast?req.ext.wrapper.includebrandcategory=1

Sample Request 

In this sample (using debug = 1), AppNexus is passed as the bidder with a minimum deal tier priority of 4. This means deals with a priority that is greater than or equal to 4 must be considered as satisfying the deal tier. 

POST request 
{
    "imp": [{
        "ext": {
            "bidder": {
                "appnexus": {
                    "dealtier": {
                        "prefix": "apnx",
                        "mindealtier": 4
                    }
                }
            }
        }
    }],
    "ext": {
        "wrapper": {
            "supportdeals": true
        }
    }
}
Pass debug=1 to get the debug object inside extension.
Debug attributeDescriptionValue

dealtiersatisfied

Represents whether corresponding deal bid has satisfied the tier.

Note: This is not applicable for /video/vast endpoint

True = deal bid has satisfied the deal tier

If attribute is empty = deal tier was not satisfied

dealpriority

The deal bid priority returned by the bidder.

Note: This is not applicable for /video/vast endpoint

Non-zero positive value = priority of the deal bid

0 = attribute will not be present

Sample response

Response has seatbid.bid object representing Ad Pod.

In this example, dealtiersatisfied = true indicates the deal bid has satisfied the deal tier. dealpriority indicates a deal bid priority of 9.

Sample response 
{
	"id": "1559039248176",
	"seatbid": [{
		"bid": [{
			"id": "9f12b1b0-18b3-43fd-bef3-e228ead461df",
			"impid": "28635736ddc2bb1",
			"price": 9.970912454221653,
			"adm": "<Ad Contents>",
			"adomain": [""]
		}],
		"seat": "prebid_ctv"
	}],
	"cur": "USD",
	"ext": {
		"debug": {
			"adpod": {
				"bidresponse": {
					"id": "1559039248176",
					"seatbid": [{
						"bid": [{
							"price": 7.859015151412768,
							"ext": {
								"partner": "appnexus",
								"prebid": {
									"targeting": {
										"pwtpb": "1.00",
										"pwtpb_cat_dur": "apnx9_30s"
									},
									"dealtiersatisfied": true,
									"dealpriority": 9
								}
							}
						}, {
							"price": 2.111897302808885,
							"ext": {
								"partner": "appnexus",
								"prebid": {
									"targeting": {
										"pwtpb": "1.00",
										"pwtpb_cat_dur": "2.1_30s"
									}
								}
							}
						}],
						"seat": "appnexus"
					}],
					"cur": "USD"
				}
			}
		}
	}
}

Set up using a primary ad server

Use this set up method if you are using a primary ad server and want to compete for programmatic and guaranteed demand. 

Endpoint:

/video/jsonThis endpoint returns targeting keys along with its values. It will not return an actual ad pod.
See OpenWrap CTV Video API Specification for more information.

In this example, we will be looking for pwtpb_cat_dur as one of the targeting key in the Ad Response. 

pwtpb_cat_dur - Provision for deal priortization

Is a targeting key returned by OpenWrap video/json endpoint. It is equivalent to Prebid Server's hb_pb_cat_dur

It is interpreted as:

pb = price bucket of the bid

cat = bid category 

dur = duration of video bid.

For example, pwtpb_cat_dur = 10.00_sports_5s indicates the bid as $10.00, belonging to the IAB Sports category, and has a duration of 5 seconds. 

Changes for deal prioritization

When deal prioritization is requested, OpenWrap replaces pb with the deal tier prefix and deal priority for the deal bids satisfying the deal tier.

For example, a deal bid is returned by the bidder:

Bid Price

Bid Category

Bid Priority

Duration

$10.00

IAB-17 (Sports)

9

5 seconds

The above deal bid satisfied the following bidder's deal tier:

PrefixMinimum Deal Priority
apnx4

In this case pwtpb_cat_dur will be changed as follows:

Old ValueNew Value
10.00_sports_5sapnx9_sports_5s

The new value indicates the bid with deal priority 9 has satisfied the bidder's deal tier, it belongs to IAB Sports category, and has a duration of 5 seconds.

pwtpb_cat_dur will be then used by the primary ad server as key-value targeting in the line item setup. This will ensure line items that represent corresponding deal are getting prioritized in auction of primary ad server.

Pass supportdeals = true in the request-level wrapper extension object of the OpenWrap Ad Pod request, as follows:

POST request 
{
    "imp": [],
    "ext": {
        "wrapper": {
            "supportdeals": true
        }
    }
}
GET request 
/video/openrtb?req.ext.wrapper.supportdeals=true
/video/vast?req.ext.wrapper.supportdeals=true


Pass the dealtier information in the impression-level bidder extension of the OpenWrap Ad Pod request, as follows:  

  1. Replace <BIDDER_PREFIX> with a string value bidder-specific prefix required for deal tiering.
  2. Replace <MINIMUM_REQUIRED_DEAL_PRIORITY> with an integer value greater than 0.
POST request 
{
    "imp": [{
        "ext": {
            "bidder": {
                "bidder1": {
                    "dealtier": {
                        "prefix": "<BIDDER_PREFIX>",
                        "mindealtier": <MINIMUM_REQUIRED_DEAL_PRIORITY>
                    }
                },
                "bidder2": {
                    "dealtier": {
                        "prefix": "<BIDDER_PREFIX>",
                        "mindealtier": <MINIMUM_REQUIRED_DEAL_PRIORITY>
                    }
                }
            }
        }
    }]
}
GET request 
imp[<INDEX>].ext.bidder=encodeURI('{"bidder1":{"dealtier":{"prefix":"<BIDDER_1_PREFIX>","mindealtier":<MINIMUM_REQUIRED_DEAL_PRIORITY> }},"bidder2":{"dealtier":{"prefix":"<BIDDER_2_PREFIX>","mindealtier":<MINIMUM_REQUIRED_DEAL_PRIORITY>}}}')


// Output - %7B%22bidder1%22:%7B%22dealtier%22:%7B%22prefix%22:%22%3CBIDDER_1_PREFIX%3E%22,%22mindealtier%22:%3CMINIMUM_REQUIRED_DEAL_PRIORITY%3E%20%7D%7D,%22bidder2%22:%7B%22dealtier%22:%7B%22prefix%22:%22%3CBIDDER_2_PREFIX%3E%22,%22mindealtier%22:%3CMINIMUM_REQUIRED_DEAL_PRIORITY%3E%7D%7D%7D


(Optional) In this sample, we used includebrandcategory to include a bid category (1 = IAB bid category) in the request-level wrapper extension object of the OpenWrap Ad Pod request:

POST request 
{
    "imp": [],
    "ext": {
        "wrapper": {
            "includebrandcategory": 1
        }
    }
}
GET request 
/video/openrtb?req.ext.wrapper.includebrandcategory=1
/video/vast?req.ext.wrapper.includebrandcategory=1

Sample Request 

In this sample (using debug = 1), AppNexus is passed as the bidder with a minimum deal tier priority of 4. This means deals with a priority that is greater than or equal to 4 must be considered as satisfying the deal tier. 

POST request 
{
    "imp": [{
        "ext": {
            "bidder": {
                "appnexus": {
                    "dealtier": {
                        "prefix": "apnx",
                        "mindealtier": 4
                    }
                }
            }
        }
    }],
    "ext": {
        "wrapper": {
            "supportdeals": true
        }
    }
}
Pass debug=1 to get the debug object inside extension.
Debug attributeDescriptionValue

dealtiersatisfied

Represents whether corresponding deal bid has satisfied the tier.

Note: This is not applicable for /video/vast endpoint

True = deal bid has satisfied the deal tier

If attribute is empty = deal tier was not satisfied

dealpriority

The deal bid priority returned by the bidder.

Note: This is not applicable for /video/vast endpoint

Non-zero positive value = priority of the deal bid

0 = attribute will not be present

Sample response

Response has seatbid.bid object representing Ad Pod.

In this example, dealtiersatisfied = true indicates the deal bid has satisfied the deal tier. dealpriority indicates a deal bid priority of 9.

Sample response 
{
	"adpods": [{
		"id": "imp176227948",
		"targeting": [{
			"pwtbst": "1"
		}]
	}],

	"ext": {
		"debug": {
			"adpod": {
				"bidresponse": {
					"id": "1559039248176",
					"seatbid": [{
						"bid": [{
							"price": 7.859015151412768,
							"ext": {
								"partner": "appnexus",
								"prebid": {
									"targeting": {
										"pwtpb": "1.00",
										"pwtpb_cat_dur": "apnx9_30s"
									},
									"dealtiersatisfied": true,
									"dealpriority": 9
								}
							}
						}],
						"seat": "appnexus"
					}],
					"cur": "USD"
				}
			}
		}
	}
}


Failure scenarios

If the bid response does not have a category

Then the bid will be rejected by OpenWrap when includebrandcategory = 1 or 2

If the same bid.id is returned by a bidder in case of multiple bids response

Then the bid will be rejected by OpenWrap when includebrandcategory = 1 or 2


FAQs

Question: Partner / Bidder not responded with creative duration

Answer: In such a case pwtpb_cat_dur will be populated using corresponding impression level max duration value. Hence, the actual ad duration may not match with the max duration

Question: How does category or advertiser exclusion works when a deal bid satisfies the deal tier? 

Answer: There are two possibilities:

    • A combination containing the highest number of deal bids, that satisfied the deal tier, will be selected on priority and then an exclusion algorithm will be applied on top of it
    • Deal bids which satisfied the deal tier will be preferred on top of other bids. These deal bid buckets will also be sorted based on bid price.

Question: Will pwtpb_cat_dur key be populated if deal bid not satisfied the tier?

Answer: Yes, if supportdeals = true for any winning bid, this key will be populated. However, it will contain the actual price bucket of the given bid, instead of deal tier prefix + deal priority.



⇧ Top

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

Table of Contents


PubMatic Website 

PubMatic Privacy Policy

All Rights Reserved Copyright 2020

This website uses cookies for analytics and personalization. Click here to learn more or change your cookie settings. By continuing to browse, you agree to our use of cookies.