Buyer OpenRTB integration guidelines
Copyright
This document is the property of TheViewPoint, LLC. ("TheViewPoint").
The information contained in this document is confidential and no part of it may be reproduced, displayed, distributed, or disclosed by any
means, unless otherwise agreed.
Disclaimer
The information provided in this document is subject to change at any time.
This document does not create any legally enforceable obligations on the part of TheViewPoint.
Introduction
This document contains integration guidelines and required information for bidders.
TheViewPoint (“Exchange”) by default utilizes IAB OpenRTB API Specification Version 2.5 (“Specification”) https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf
Integration via previous versions (2.2, 2.3, 2.4) is available upon request.
This document is intended to be used in addition to the Specification.
All IAB-required objects and fields are present in all the bid requests.
Recommended and optional fields are populated where possible, taking into account Exchange policies and data availability.
Bidders should be ready to receive and be able to read any field according to the Specification.
Transport, encoding, data format
HTTP POST method is used to send Bid requests.
SSL is supported but not recommended.
HTTP Keep-Alive is recommended.
Bid requests and responses are formatted as JSON with UTF-8 encoding.
The bid request specifies the representation as a mime type using the “Content-Type” HTTP header.
The mime type for the standard JSON representation is “application/json”.
The format of the bid response should be the same as the bid request. Content-Type: application/json
Bid requests include an Accept-Encoding: gzip header to indicate support for gzipped bid responses.
Network
TheViewPoint is located in AWS US-EAST (Ohio). Other endpoint locations are available upon request.
The bid response timeout threshold (tmax) is 300ms.
We recommend bidders to be located in a data center near AWS US-EAST.
Limit QPS for testing period 500 (max)
Auction
TheViewPoint offers CTV supply in Open Auction and Private Marketplaces (“PMP”).
By default, the auction works on a “second price” basis. Publishers may choose to use “first price” in the PMP which would be reflected in the bid
Request at the field. In any case, the clearing price will not exceed the winning bid price.
After selecting the winner an Exchange will send a notification through the nurl link.
Loss notification and passing loss reason are supported to some extent via provided lurl and substitution macro ${AUCTION_LOSS}.
Bidders are expected to send HTTP 204 No Content response in case of no bid is made.
A well-formed no bid response with a reason code is supported and recommended during the integration period.
Ad markup serving options
Exchange supports both methods of serving ad markup in accordance with the Specification (section 4.3):
On the win notice ( bid.nurl attribute)
Directly in the bid itself ( bid.adm attribute)
Supported video response protocols of the ad markup:
Value | Description |
|---|---|
2 | VAST 2.0 |
3 | VAST 3.0 |
5 | VAST 2.0 Wrapper |
6 | VAST 3.0 Wrapper |
In case of a wrapper response, TheViewPoint will make a server side attempt to retrieve the ad and form a combined VAST response with the InLine item.
Substitution Macros
Prior to calling a win or billing notice URL, the Exchange will search the specified URL for any of the defined macros and replace them with the appropriate data. These same substitution macros can also be placed in the ad markup.
Macro | Description |
|---|---|
${AUCTION_ID} | ID of the bid request; from BidRequest.id attribute. |
${AUCTION_BID_ID} | ID of the bid; from BidResponse.bidid attribute. ${AUCTION_ |
${AUCTION_IMP_ID} | ID of the impression just won; from imp.id attribute. |
${AUCTION_SEAT_ID} | ID of the bidder seat for whom the bid was made. |
${AUCTION_AD_ID} | ID of the ad markup the bidder wishes to serve; from bid.adid attribute |
${AUCTION_PRICE} | Clearing price using the same currency and units as the bid. |
${AUCTION_CURRENCY} | The currency used in the bid (explicit or implied); for confirmation only. |
${AUCTION_LOSS} | Loss reason codes. |
Rendering an ad
Exchange does not pre-cache ad markup.
Publishers can choose to request an ad and show it immediately or to pre-cache an ad in the device ahead of time and show it later.
Example of a bid request
{ "id": "78e9881a-d17a-42fa-a336-547bce15691c",
"imp": [
{
"id": "1",
"video": {
"mimes" : [
"video/mp4",
"video/x-mp4",
"video/mp4-h264",
"application/x-mpegurl",
"application/vnd.apple.mpegurl"
],
"minduration" : 5,
"maxduration": 60,
"protocols": [2, 3, 5, 6],
"w": 1920,
"h": 1080,
"startdelay": -1,
"placement": 1,
"linearity" : 1,
"battr": [9, 10, 11 ,12 ,13, 14, 15, 16, 17]
},
"pmp": {
"private_auction": 1,
"deals": [
{
"id": "5f90e0d6-5ea7-4351-be90-c5629e2860b9",
"bidfloor": 16.0,
"at": 3,
"wseat": ["db507adb", "db507ada"]
}
]
},
"instl" : 1,
"secure" : 1
}
],
"app": {
"id": "AA21S0101",
"name": "FuboTV",
"storeurl": "https://channelstore.roku.com/en-gb/details/43465/fubotv ",
"bundle" : "43465",
"domain" : "http://fubo.tv ",
"cat": ["IAB17"],
"privacypolicy" : 1,
"publisher": {
"id" : "AA21",
"Name" : "FuboTV",
"cat" : ["IAB17"],
"domain" : "http://fubo.tv "
},
"content": {
"livestream": 1
},
},
"device": {
"ua": "Roku/DVP-9.30 (AE9.30E04170A)",
"geo": {
"country": "usa",
"region": "fl",
"city": "longwood",
"zip": "32779"
},
"lmt": 0,
"ip": "172.58.207.103",
"devicetype": 7,
"make" : "Roku",
"model" : "Digital Video player",
"os": "Roku OS",
"osv" : "9.30",
"h": 1080,
"w": 1920,
"language": "en",
"ifa": "ecd7244e-e8e2-4de6-ad5f-30a570299d9a"
},
"regs": {
"coppa": 0
},
"tmax": 400
}