Vistar Media exposes an OpenRTB 2.x based bidding protocol to allow third parties to bid on out-of-home (OOH) inventory in real time. JSON encoding is assumed for all messages below unless otherwise specified. Bidder registration takes place offline. In this process, the two parties will share HTTP endpoints for bid requests.
See OpenRTB API Specification Version 2.5 for more information.
Vistar Media’s OpenRTB support is through the open exchange or Private Marketplace (PMP) deals. The Bid request section in this article outlines the request based on the transaction type. You can view the relevant sections for a sample bid request and response flow:
For any commonly asked questions, see the FAQs section later in this article.
Bid request
Depending on the eligible transaction types, you can view a sample request that is sent to a bidder:
- Standard request (eligible for open exchange bids and PMPs)
- Open exchange only
- PMP only
View Open RTB: Bid request and bid response definitions for a full list of the bid request fields.
Important to note:
- If the request is eligible for both open exchange and PMPs, there must be a
pmpobject and within the object,private_auctionmust be set to0. - Because Vistar’s exchange operates a second price auction, the
bidrequest.atobject must be set to2. See the FAQs section for details.
Sample request
{
"id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
"imp": [
{
"id": "display-area-3-1",
"banner": {
"w": 1920,
"h": 1080,
"format": [
{
"w": 1920,
"h": 1080
},
{
"w": 1366,
"h": 768
}
],
"mimes": [
"image/jpeg",
"image/png"
],
"ext": {
"dooh": {
"impsPerSpot": 3.5668650793650793
}
}
},
"video": {
"mimes": [
"video/mp4",
"video/mpeg"
],
"w": 1920,
"h": 1080,
"protocols": [
3,
7
],
"ext": {
"dooh": {
"impsPerSpot": 1.7834325396825397,
"impsPerSecond": 0.11889550264550265
}
}
},
"bidfloor": 5,
"bidfloorcur": "USD",
"pmp": {
"private_auction": 0,
"deals": [
{
"id": "gspAwTCiQViuqpIt9z1CpA",
"bidfloor": 3,
"at": 3
}
]
},
"exp": 3565
}
],
"site": {
"domain": "Test-Seller.com",
"publisher": {
"name": "Test Seller"
}
},
"device": {
"ua": "Vistar Media 1.0",
"geo": {
"lat": 39.986855,
"lon": -75.196442,
"zip": "19121",
"type": 1
},
"ext": {
"dooh": {
"industryid": "testvenue119",
"publicid": "fziowv-testvenue119",
"venueTypeIds": [
8,
804
]
}
}
},
"at": 2,
"tmax": 1000,
"cur": [
"USD"
],
"wlang": [
"en"
]
}
Important to note:
- There is no
pmpobject in the bid request. - The price is per 1000 spots and it must be higher than the bid floor passed in the request on a CPM basis.
- Because Vistar’s exchange operates a second price auction, the
bidrequest.atobject must be set to2. See the FAQs section for details.
Sample request
{
"id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
"imp": [
{
"id": "display-area-3-1",
"banner": {
"w": 1920,
"h": 1080,
"mimes": [
"image/jpeg",
"image/png"
],
"ext": {
"dooh": {
"impsPerSpot": 3.5668650793650793
}
}
},
"video": {
"mimes": [
"video/mp4",
"video/mpeg"
],
"w": 1920,
"h": 1080,
"protocols": [
3,
7
],
"ext": {
"dooh": {
"impsPerSpot": 1.7834325396825397,
"impsPerSecond": 0.11889550264550265
}
}
},
"bidfloor": 5,
"bidfloorcur": "USD",
"exp": 3565
}
],
"site": {
"domain": "Seller.com",
"publisher": {
"name": "Seller"
}
},
"device": {
"ua": "Vistar Media 1.0",
"geo": {
"lat": 39.986855,
"lon": -75.196442,
"zip": "19121",
"type": 1
},
"ext": {
"dooh": {
"industryid": "testvenue119",
"publicid": "fziowv-testvenue119",
"venueTypeIds": [
8,
804
]
}
}
},
"at": 2,
"tmax": 1000,
"cur": [
"USD"
],
"wlang": [
"en"
]
}
Important to note:
- If the request is only eligible for PMPs (not open exchange), the
pmpobject must contain"private_auction": 1.The request will only accept bids for the listed deal IDs. - Because Vistar’s exchange operates a second price auction, the
bidrequest.atobject must be set to2. See the FAQs section for details.
Sample request
{
"id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
"imp": [
{
"id": "display-area-3-1",
"banner": {
"w": 1920,
"h": 1080,
"mimes": [
"image/jpeg",
"image/png"
],
"ext": {
"dooh": {
"impsPerSpot": 3.5668650793650793
}
}
},
"video": {
"mimes": [
"video/mp4",
"video/mpeg"
],
"w": 1920,
"h": 1080,
"protocols": [
3,
7
],
"ext": {
"dooh": {
"impsPerSpot": 1.7834325396825397,
"impsPerSecond": 0.11889550264550265
}
}
},
"bidfloor": 5,
"bidfloorcur": "USD",
"pmp": {
"private_auction": 1,
"deals": [
{
"id": "gspAwTCiQViuqpIt9z1CpA",
"bidfloor": 3,
"at": 3
}
]
},
"exp": 3565
}
],
"site": {
"domain": "Seller.com",
"publisher": {
"name": "Test Seller"
}
},
"device": {
"ua": "Vistar Media 1.0",
"geo": {
"lat": 39.986855,
"lon": -75.196442,
"zip": "19121",
"type": 1
},
"ext": {
"dooh": {
"industryid": "testvenue119",
"publicid": "fziowv-testvenue119",
"venueTypeIds": [
8,
804
]
}
}
},
"at": 2,
"tmax": 1000,
"cur": [
"USD"
],
"wlang": [
"en"
]
}
Bid response
It is recommended to submit multiple seat bids per bid request. Vistar’s SSP will evaluate all seat bids from all DSPs when selecting the winning response. The following example of a BidResponse will be sent to Vistar. View Open RTB: Bid request and bid response definitions for a full list of the bid response fields.
Important to note:
- Deal ID should only be included if the bid is for a specific deal.
- An open exchange bid should not pass a deal ID.
cator IAB 1.0 category is not explicitly required but DSPs are strongly encouraged to pass the field- One of the following fields must be passed in a given bid response, depending on the media type:
iurl—If the bid is for images and there is no ad markup for the creative.adm—If the bid is for video, or if the bid is for an image and there is ad markup for the image creative. In the case of images, this field would be used when the creative is hosted on a third party ad server.
If both fields are passed, Vistar recognizes theiurlfield and ignores the contents ofadm.
Sample response
{
"id": "607abcef-0dcc-41a4-ba0b-ad3bXXXXXXXX",
"seatbid": [
{
"group": 0,
"seat": "seatID",
"bid": [
{
"id": "bidid1",
"impid": "display-0",
"dealid": "pdoEaNmbSYe5KqXXXXXXXX",
"price": 933.5,
"adomain": [
"cats.com"
],
"cid": "<cid>",
"crid": "<crid>",
"adm": "<VAST TAG>",
"iurl": "<image asset url>",
"cat": ["IAB3-1"],
"lurl": "<LURL>",
"nurl": "<NURL>",
"ext": {
"imptrackers": [<impression_url>...]
}
}
]
}
]
}
Impressions and financials
The following sections outline Vistar's preferences for handling impressions and financials:
In OOH, multiple impressions are available for a given opportunity (also known as a spot). The available impressions vary depending on asset duration, whether the asset is image versus video, as well as the specifics of the OOH screen itself. For a given opportunity, impressions are then calculated with some base value per spot regardless of duration plus and a per second value times the duration.
Communicating available impressions over RTB requires extension objects. It is our preference that these objects are specified on the Video objects, as described below. and Banner
Macros contained in impression URLs, lurl, nurl, and burl will be substituted. Vistar supports IMPRESSIONS , AUCTION_PRICE, DISPLAY_TIME and AUCTION_LOSS
AUCTION_PRICE—Contains the price of running this transaction, for the calculated impressions, 1000 times.IMPRESSIONS—Contains the calculated impression values depending on the asset type and duration.DISPLAY_TIME—Contains the time the ad was played by the media owner in unix epoch seconds. Note: this should only be passed on impression URLs andburlAUCTION_LOSS—Contains the loss reason when a bid response loses in the auction. Note: this should only be passed onlurl. View Vistar Loss Reason Codes and Definitions to review the full list of supported loss reasons.
The potential time window between when an ad is requested and when it is shown may be much larger than on a real-time exchange. Some devices experience intermittent connectivity, so there are select times throughout the day at which they can fetch ads and content. Such devices may schedule up to three hours worth of advertisements over a relatively short period of time. For each request we will know the exact point in time it intends to play the ad.
Accordingly, there is some latency between the time of BidRequest and when the impression URLs will be hit. This is variable per media owner, but should not be more than a few hours. For each bidder, the media owners can be configured so only inventory that adheres to the bidder’s latency requirements are made available.
If a bidder supports returning the burl field, this can be provided in lieu of impression and tracking URLs.
While nurl will be hit at auction time, Vistar does not consider a transaction billable until the impression URL or burl are fired.
Tracking URLs for start and complete events in VAST will also be hit at about the same time as impression URLs.
It is our preference that the price and bidfloor fields contain CPMs, but we can support bidders that require different behavior. For example, price instead containing a final price value.
An example of our preferences for financials during BidRequest/Response is below. This assumes the agreed deal contains a bidfloor of 5.
Example video
On the BidRequest, video.ext.dooh.impsPerSecond is 12.1, and video.ext.impsPerSpot is 5.2.
- If a DSP bids with a video creative of
15seconds, the impressions available for this opportunity are then5.2+ (12.1*15) =186.7. - The price of these impressions is then (
5) */1000186.7=.9335dollars. - A corresponding
Bidon thisBidRequestshould contain a price value of933.5, as the deal is fixed price. - An
AUCTION_PRICEmacro would contain a value of933.5. - An
IMPRESSIONSmacro would contain a value of186.7.
Example image
On the BidRequest, banner.ext.dooh.impsPerSpot is 180.2.
- If a DSP bids with an image creative, the impressions available for this opportunity are then simply
180.2. - The price of these impressions is then (
5/1000) *180.2=.901dollars. - A corresponding
Bidon thisBidRequestshould contain a price value of901, as the deal is fixed price. - An
AUCTION_PRICEmacro would contain a value of901. - An
IMPRESSIONSmacro would contain a value of180.2.
FAQs
The following outlines some common questions and answers to help you better understand OpenRTB and Vistar.
Vistar’s creative transcoding process takes incoming video creatives and converts them into multiple formats required to deliver across a variety of screen specifications. The creative approval process passes each new creative to an approval queue for the relevant media owners. The media owner will review, and then approve or deny the creative in Vistar’s SSP.
Our bidding process incorporates lazy creative transcoding and approval. When we receive an asset for the first time in a BidResponse, the asset will be ingested, transcoded, and sent for approval to the media owner. Received Bids referencing this asset will be lost until it is approved by the media owner. Approval time varies depending on the media owner, but is commonly a few hours to a day.
While only video creatives are transcoded, image creatives are still ingested for media owner approval.
Vistar’s exchange operates a second price auction based on the floor price set by the media owner. The highest bidder wins the auction and then pays the bid price of the second-highest bidder.
The following is an example of buyers bidding in the second price auction in Vistar’s exchange.
When you win the bid in the auction, your ad is sent to a media owner’s screen in near real-time. For out-of-home (OOH) campaigns, your ad can be seen by many viewers. Vistar works with several auditing bodies (such as Nielsen, Geopath, and so on) that provide a standard impression methodology for the industry.
You can view the Best practice guide that outlines technical and operational changes that may affect your integration. If you have additional questions after reviewing the guide, you can contact support@vistarmedia.com for support.