OpenRTB Video Ads

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.

Bid response fields

Key fields in a video bid response include the following:

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.

Pretargeting

To receive video inventory, OpenRTB buyers must have a pretargeting configuration that includes video inventory.

Example bid request and response

Bid request

Show Me

{
  id: "XIsz9QAHfAYKj3oDMQ3QOg",
  imp: [{
    id: "1",
    banner: {
      w: 300,
      h: 250,
      format:     [{
        w: 300,
        h: 250
      },{
        w: 250,
        h: 250
      }],
      battr:     [5]
    },
    video: {
      mimes:     [video/mp4],
      linearity: 1,
      protocols:     [2,3,5,6],
      w: 300,
      h: 250,
      skip: 1,
      battr:     [5],
      playbackmethod:     [6],
      plcmt: 3
    },
    displaymanager: "GOOGLE",
    tagid: "2111189154",
    bidfloor: 0.01,
    bidfloorcur: "USD",
    secure: 1,
    native: {
      request_native: {
        ver: "1.2",
        assets:       [{
          id: 1,
          required: 1,
          title: {
            len: 25
          }
        },{
          id: 2,
          data: {
            type: 2,
            len: 90
          }
        },{
          id: 3,
          data: {
            type: 12,
            len: 15
          }
        },{
          id: 4,
          data: {
            type: 1,
            len: 25
          }
        },{
          id: 5,
          img: {
            type: 3,
            wmin: 1200,
            hmin: 627
          }
        },{
          id: 6,
          img: {
            type: 2,
            wmin: 100,
            hmin: 100
          }
        },{
          id: 7,
          img: {
            type: 1,
            wmin: 100,
            hmin: 100
          }
        },{
          id: 8,
          data: {
            type: 3,
            len: 5
          }
        },{
          id: 9,
          video: {
            mimes:           [video/mp4]
          }
        }],
        eventtrackers:       [{
          event: 1,
          methods:         [1]
        }],
        adx_ext: {
          style_id: 188961,
          style_height: 250,
          style_width: 300
        }
      },
      ver: "1.2",
      battr:     [5]
    },
    metric:   [{
      type: "click_through_rate",
      value: 0.0006341254338622093,
      vendor: "EXCHANGE"
    },{
      type: "video_completion_rate",
      value: 0.017279919236898422,
      vendor: "EXCHANGE"
    },{
      type: "viewability",
      value: 0.7,
      vendor: "EXCHANGE"
    },{
      type: "session_depth",
      value: 1,
      vendor: "EXCHANGE"
    }],
    adx_ext: {
      billing_id:     [12345567890],
      publisher_settings_list_id:     [5509324247698256194,14109776396365339331],
      allowed_vendor_type:     [3,42,79,4463,4513,4538,4625],
      ampad: "AMP_AD_ALLOWED_AND_NOT_EARLY_RENDERED"
    }
  }],
  site: {
    page: "https:/example.com/school",
    publisher: {
      id: "pub-783270600012345",
      adx_ext: {
        country: "IN"
      }
    },
    content: {
      contentrating: "DV-G",
      language: "en"
    },
    mobile: 1,
    adx_ext: {
      amp: "DIALECT_HTML"
    }
  },
  device: {
    ua: "Mozilla/5.0 (iPad; CPU OS 12_1_4 like Mac OS X) FBOP/5;FBRV/0]",
    ip: "121.222.242.0",
    geo: {
      lat: -26.487831115722656,
      lon: 153.0424346923828,
      country: "AUS",
      region: "AU-QLD",
      zip: "4562",
      utcoffset: 600
    },
    make: "apple",
    model: "ipad",
    os: "iOS",
    osv: "12.1.1",
    w: 768,
    h: 1024,
    pxratio: 2,
    devicetype: 5
  },
  user: {
    id: "CAESEK6jGeddIeo_opp-WrY",
    buyeruid: "anFTbmRJMVF3VXy0",
    customdata: "anFTbmRJMVVXy0",
    data:   [{
      id: "DetectedVerticals",
      name: "DoubleClick",
      segment:     [{
        id: "1263",
        value: "0.5"
      },{
        id: "625",
        value: "0.1"
      }]
    }]
  },
  at: 2,
  tmax: 122,
  cur: [USD],
  bcat: [IAB7-39],
  adx_ext: {
    google_query_id: "ANy-zJFcyG8sUO0_hYbujPqNXbB3bPA"
  }
}

Bid response

Show Me

{
  "id": "AB1abcDEfghijklMno2pqr",
  "seatbid": [
    {
      "seat": "Example Seat",
      "bid": [
        {
          "id": "12345678901234567890",
          "impid": "1",
          "price": 15,
          "adid": "AB1234-1234",
          "adm": "https://example.com/AdX/win?tag=AbcdEfGhIJ0kLMN2OPQ2RST3UVXyZAB2Cde114eF
          "cid": "12345678901",
          "crid": "1234",
          "adomain": [
            "www.example.com"
          ]
        }
      ]
    }
  ],
  "cur": "USD",
  "bidid": "1234567890123456789"
}

Glossary

See Authorized Buyers video glossary.