OpenRTB specification

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:

View Open RTB: Bid request and bid response definitions for a full list of the bid request fields.

Standard request

Important to note:

  • If the request is eligible for both open exchange and PMPs, there must be a pmp object and within the object, private_auction must be set to 0.
  • Because Vistar’s exchange operates a second price auction, the bidrequest.at object must be set to 2. See the FAQs section for details.

Sample request

{
    "id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
    "imp": [
        {
            "id": "display-area-3-1",
            "banner": {
                "w": 1280,
                "h": 800,
                "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"
    ]
}
Open exchange only

Important to note:

  • There is no pmp object 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.at object must be set to 2. See the FAQs section for details.

Sample request

{
    "id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
    "imp": [
        {
            "id": "display-area-3-1",
            "banner": {
                "w": 1280,
                "h": 800,
                "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"
    ]
}
PMP only

Important to note:

  • If the request is only eligible for PMPs (not open exchange), the pmp object 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.at object must be set to 2. See the FAQs section for details.

Sample request

{
    "id": "297273f0-f77f-40bd-b2fb-0b6fXXXXXXXX",
    "imp": [
        {
            "id": "display-area-3-1",
            "banner": {
                "w": 1280,
                "h": 800,
                "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.

Sample response

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.
  • 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.
    • adm—If the bid is for videos.
      If both fields are passed, Vistar recognizes the iurl field and ignores the contents of adm.

Sample response

{
  "id": "607abcef-0dcc-41a4-ba0b-ad3bXXXXXXXX",
  "seatbid": [
    {
      "group": 0,
      "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>",
  "lurl": "<LURL>",
          "nurl": "<NURL>",
          "ext": {
            "imptrackers": [<impression_url>...]
          }
        }
      ]
    }
  ]
}

Impressions and financials

The following sections outline Vistar's preferences for handling impressions and financials:

Impressions

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 and Banner objects, as described below.

Macros

Macros contained in impression URLs, lurl, nurl, and burl will be substituted. Vistar supports IMPRESSIONS , AUCTION_PRICE, and DISPLAY_TIME

  • 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 and burl
Impression URLs

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

Tracking URLs for start and complete events in VAST will also be hit at about the same time as impression URLs.

Financials

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 15 seconds, the impressions available for this opportunity are then 5.2 + (12.1 * 15) = 186.7.
  • The price of these impressions is then (5/1000) * 186.7 = .9335 dollars.
  • A corresponding Bid on this BidRequest should contain a price value of 933.5, as the deal is fixed price.
  • An AUCTION_PRICE macro would contain a value of 933.5.
  • An IMPRESSIONS macro would contain a value of 186.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 = .901 dollars.
  • A corresponding Bid on this BidRequest should contain a price value of 901, as the deal is fixed price.
  • An AUCTION_PRICE macro would contain a value of 901.
  • An IMPRESSIONS macro would contain a value of 180.2.

FAQs

The following outlines some common questions and answers to help you better understand OpenRTB and Vistar.

How does creative approval and transcoding work?

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.

How do auctions work in Vistar’s exchange?

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. 

second_price_auction.jpeg

 

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.

Currently, we only deliver PMPs through Vistar’s SSP. How can we start bidding on the open exchange?

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.

Was this article helpful?
0 out of 0 found this helpful