This guide outlines the integration requirements for RTB buying using the OpenRTB protocol. This guide should be used in conjunction with the OpenRTB Integration guide where the fields discussed here are described in detail.
If you buy on iOS apps with HTML snippets that include <video>
tags you
must include the playsinline
attribute on the video tag. Otherwise users have a very
poor experience where video ads that are supposed to play within the creative seem to pop-out to
fullscreen. Ads that don't respect this will be blocked.
Buyer requirements
New RTB buyers should develop their bidders using the latest protocol buffer and the information outlined in the following sections. To download the protocol, see the reference data page. For information on developing a bidder, see Process the Request and Build the Response.
Supported macros
The following macros are supported on in-stream video creatives:
%%CACHEBUSTER%%
%%WINNING_PRICE%%
Note that the macro replacement is allowed in the video URL but not within the actual VAST XML.
Click macros (such as CLICK_URL_ESC
) are not necessary
because Authorized Buyers includes its click trackers in a VAST wrapper.
Therefore, click macros are not supported for in-stream video ads.
For more information about supported macros,
see Specify macros
under Build the Response.
Video object details
The OpenRTB protocol uses a Video
message, defined in the
openrtb-proto.txt file to identify video requests
and to provide additional video-specific information about the request.
See the list of Video message fields in the OpenRTB Integration guide for detailed descriptions and examples.
Other video bid request fields
The signals below are not all unique to video creatives, but are key parts of the bid request.
Imp object fields
This object describes an ad placement or impression being auctioned.
banner |
A Banner object; required if the impression is offered as a banner ad opportunity. |
video |
Indicates the type of impression being offered, in this case video. Note that in-banner
video is allowed if the imp object includes both banner and
video objects. |
tagid |
Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer. |
bidfloor |
Minimum bid for this impression expressed in CPM. |
bidfloorcur |
A single currency, obtained from the included billing_id. |
See the Imp object section in the OpenRTB guide for additional details.
Device object fields
The fields in the Device
object provide information about the targeted device.
ua |
Browser user agent string. |
ip |
IPv4 address closest to device. |
geo |
Location of the device assumed to be the user's current location defined by a Geo object. |
devicetype |
The general type of device. |
ifa |
ID sanctioned for advertiser use in the clear (for example, not hashed). ifa is supported for connected TV devices such as Roku, Apple TV, Fire TV, Xbox. |
See the Device object section in the OpenRTB guide for additional details.
Site object
The fields in the Site
object provide information about the site with ad-supported content.
page |
URL of the page where the impression will be shown. |
publisher |
Details about the Publisher object of the site. |
content |
Details about the Content within the site. |
See the Site object section in the OpenRTB guide for additional details.
User object
The fields in the User
object provide information about the site with ad-supported content.
id |
Exchange-specific ID for the user. At least one of id or buyerid is recommended. |
data |
Details about the Publisher object of the site. |
See the User object section in the OpenRTB guide for additional details.
Bid request inventory fields
The video bid request also contains information about content types and any specified companion ads.
mimes
- Allowlist of content MIME types supported.
companionad
- Array of Banner objects if companion ads are available.
id
- ID of the bid request to which this is a response.
seatbid
- Array of Seatbid objects; one or more required if a bid is to be made.
seat
-
A
Seatbid
object; ID of the buyer seat (for example, advertiser, agency) on whose behalf this bid is made. bid
- Array of one or more Bid objects each related to an impression.
Bid response fields
Key fields in a video bid response include the following:
Pretargeting
To receive video inventory, OpenRTB buyers must have a pretargeting configuration that includes video inventory.