Prebid Server Video Endpoint

This document describes the behavior of the Prebid Server video endpoint in detail.

Video Endpoint

POST /openrtb2/video

Overview

Prebid Server (PBS) supports competitve separation for ad pod display from primary ad servers such as Freewheel and DFP. PBS, on receiving this endpoint, will pass default settings and stored_request parameters to one or more OpenRTB requests, which will then be sent to the appropriate SSPs.

The process is similar to Prebid.js client side support for this feature.

Process

  1. Application makes request for a video stream.
  2. An SSAI Server sends a video request to PBS, specifying the pod requirements.
  3. PBS sends a request for bids to selected demand partners by relaying OpenRTB requests to them.
  4. Demand partners return a bid response to PBS. If competitive seperation is enabled, PBS peforms category translation on each bid. Whether category translation is required or not, the bids are stored in prebid cache.
  5. PBS generates key-value pairs that are comprised of price, category, and duration values. The key is hb_pb_cat_dur and each component of the key name after the hb represents a related value.
        
         _pb represents the price bucket.
         _cat indicates the industry code that is derived from the category translation.
         _dur is the length of the bid response in seconds.
        
    A PBS generated key-value of hb_pb_cat_dur = 1200_399_30s would indicate:
        
         A price bucket of $12.00 (or the local currency).
         The industry represented by id 399.
         A duration of 30 seconds.
        
    These key-values are returned to the SSAI server as part of the video response.

  6. The SSAI server parses the returned key-values, appending them as a query string to the ad server request URL and submits the request.
  7. The ad server returns the optimized pod.
  8. The SSAI server requests the creatives from prebid cache.
  9. The SSAI server requests the content from the content host and stitches the creatives and content together.
  10. The stitched stream is returned to the application.



Parameters

Param Scope Type Description
storedrequestid Optional (Required for Xandr PBS) String The id used to look up the entire request from a stored configuration in the database.
podconfig Required Object Container object for describing all the pod configurations.
podconfig.durationrangesec Required Integer[] Range of ad durations allowed in the response. See pod duration range for more details.
podconfig.requireexactduration Optional Boolean Flag indicating exact ad duration requirement. Default is false.
podconfig.pods Required Object[] Container object for describing the adPod(s) to be requested.
site Required Object Container object for the URL of the impression to be shown. Can be excluded if app is included.
site.page Required String URL of the page where the impression will be shown.
site.publisher.id Required String Appnexus member ID.
app Required Object Container object for app information where the impression is to be shown. Can be excluded if site is included.
app.bundle Optional String A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID.
app.domain Required String The domain of the app.
app.name Optional String The name of the app.
app.publisher.id Required String Appnexus member ID.
app.storeurl Optional String App store URL for an installed app.
video Required Object Container object for video player data.
video.w Optional Integer Width of the video player in device independent pixels.
video.h Optional Integer Height of the video player in device independent pixels.
video.mimes Required String[] Player supported mime types. Example: [“video/mp4”]
video.protocols Required Integer[] Array of supported video protocols.
includebrandcategory Optional Object Container Object for passing Category inputs.
includebrandcategory.primaryadserver Optional Integer The ad server used by the publisher. Supported Values 1- Freewheel , 2- DFP.
includebrandcategory.publisher Optional String Identifier for the Publisher.
content Optional Object Miscellaneous content meta data that can be used for targeting the adPod(s)
content.episode Optional Integer The episode number.
content.title Optional String The episode name.
content.season Optional String The season name.
content.series Optional String The series name.
content.len Optional Integer The length of the content in seconds.
content.livestream Optional Integer The content mode indicator for VOD or Live. Supported values: integer 0 = not live, 1 = content is live (e.g., stream, live blog).
user Optional (recommended) Object Container object for the user of of the actual device.
user.buyeruids Optional Object Container objects for all the SSP UserIDs to send to the SSPs endpoint. See buyeruids for more details.
user.yob Optional Integer Year of birth as a 4-digit integer.
user.gender Optional String Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
user.keywords Optional String Comma separated list of keywords, interests, or intent.
user.gdpr Optional Object Container object for GDPR. See GDPR for more details.
device Optional (recommended) Object Container object for device specific data.
device.ua Optional String Browser user agent string.
device.dnt Optional Integer Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
device.lmt Optional Integer “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
device.ip Optional String IP address of the device making the ad request.
device.os Optional String Device operating system. Example “iOS”.
device.w Optional Integer Physical width of the screen in pixels.
device.h Optional Integer Physical height of the screen in pixels.
device.ifa Optional String ID sanctioned for advertiser use in the clear (i.e., not hashed).
device.didshal Optional String Hardware device ID (e.g., IMEI); hashed via SHA1.
device.didmd5 Optional String Hardware device ID (e.g., IMEI); hashed via MD5.
device.dpidsha1 Optional String Platform device ID (e.g., Android ID); hashed via SHA1.
device.dpidmd5 Optional String Platform device ID (e.g., Android ID); hashed via MD5.
device.macsha1 Optional String MAC address of the device; hashed via SHA1.
device.macmd5 Optional String MAC address of the device; hashed via MD5.
pricegranularity Optional (recommended) Object The price range in varying increments that the CPM of the ad unit will fall into. Visit our price granualarity overview for more details.
pricegranularity.precision Optional Object If precision is omitted, it will default to 2.
pricegranularity.range Optional (recommended) Array See price range for details.

Pod Duration Range

The podconfig.durationrangesec is an array containing integers representing the range of ad durations allowed in the pod in seconds. For example:

durationrangesec = [15, 30] 

These values would indicate that ad durations of 15 ansd 30 seconds were allowed with this bid.

If podconfig.requireexactduration is set to false, then the ads durations will be rounded up to the closest value in the durationrangesec array. Implicit minimum bid duration is 0.

Using the values above, a ten second bid would be rounded to 15 seconds and an eighteen second bid would be rounded to 30 seconds.

If podconfig.requireexactduration is set to true, then only the ads that are the exact duration match to the durationrangesec array will be allowed.

Again, using the values above, a 15 second bid will be allowed whereas an 18 second bid will be rejected.

Pods

These are the parameters for the pod subobject:

Param Scope Type Description
podconfig.pods Required Object Container object describing the adPod(s) to be requested.
pod.podid Required Integer Unique id of the pod within a particular request.
Recommendation: Order these numerically, with increment of 1.
pod.adpoddurationsec Required Integer Duration of the adPod.
pod.configid Required Integer ID of the stored config that corresponds to a single pod request for all included adapters.

Video Protocols

A streaming protocol is a standardized method for delivering multimedia (usually video or audio) over the internet. It defines a method for sending “chunks” of content from one device to another and subsequently the method for reassembling those “chunks” into playable content.

To indicate which protocol or protocols you wish to use for content management, pass an array of integers, each integer representing a video protocol. The table below list the integer/video protocol relationship.

Integer Protocol
1 VAST 1.0
2 VAST 2.0
3 VAST 3.0
4 VAST 1.0 Wrapper
5 VAST 2.0 Wrapper
6 VAST 3.0 Wrapper
7 VAST 4.0
8 VAST 4.0 Wrapper
9 DAAST 1.0
10 DAAST 1.0 Wrapper

Buyer UIDs

The user.buyeruids is an optional, but recommended parameter. It is an object that contains all the SSP UserIDs to send to the SSPs endpoint. They are passed as key-value pairs: {bidder_name:bidder_specific_userid}.

These are the supported (registered) bidder names.

  • “33across”
  • “adform”
  • “adkernelAdn”
  • “adtelligent”
  • “appnexus”
  • “audienceNetwork”
  • “beachfront”
  • “brightroll”
  • “conversant”
  • “eplanning”
  • “grid”
  • “gumgum”
  • “ix”
  • “lifestreet”
  • “openx”
  • “pubmatic”
  • “pulsepoint”
  • “rhythmone”
  • “rubicon”
  • “somoaudience”
  • “sonobi”
  • “sovrn”
  • “yieldmo”

GDPR

General Data Protection Regulation (GDPR) is designed to protect all European Union citizens from privacy and data theft. For more information on how Prebid works with GDPR visit our page on the GDPR module

The user object has a gdpr subobject that contains data about the user’s GDPR preferences.

Param Scope Type Description
user.gdpr Optional Object Container object describing user GDPR preferences.
gdpr.consentrequired Optional Boolean Indicates whether GDPR is in effect.
gdpr.consentstring Optional String String that contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.

Price Range

The pricegranularity subobject range describes the maximum price point for the price range and the increments to traverse that range. Visit our price granualarity overview for more details.

Param Scope Type Description
range Optional Object Container object price granualarity range.
range.max Optional Float  
range.increment Optional Float  

Examples

Post Request

 {
  "storedrequestid": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  "podconfig": {
    "durationrangesec": [
      15,
      30
    ],
    "pods": [
      {
        "podid": 1,
        "adpoddurationsec": 60,
        "configid": "fba10607-0c12-43d1-ad07-b8a513bc75d6"
      },
      {
        "podid": 2,
        "adpoddurationsec": 60,
        "configid": "8b452b41-2681-4a20-9086-6f16ffad7773"
      }
    ]
  },
  "site": {
    "page": "http://www.foobar.com/1234.html"
  },
  "user": {
    "yob": 1982,
    "gender": "M",
    "buyeruids": {
      "appnexus": "unique_id_an"
    },
    "gdpr": {
      "consentrequired": false,
      "consentstring": ""
    }
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
    "ip": "123.145.167.10",
    "devicetype": 1,
    "ifa": "AA000DFE74168477C70D291f574D344790E0BB11"
  },
  "includebrandcategory": {
    "primaryadserver": 1
  },
  "video": {
    "w": 640,
    "h": 480,
    "mimes": [
      "video/mp4"
    ],
    "protocols": [
      2,
      3
    ]
  },
  "content": {
    "episode": 6,
    "title": "episodeName",
    "series": "TvName",
    "season": "season3",
    "len": 900,
    "livestream": 0
  }
}

Post Response

The POST response contains an array of adPod objects which represents the adPods in the request. Each value of the adPod object (podid:1, podid:2, etc) contain the key-value targeting for those bids and optionally any errors encountered.

{
  "adPods": [
    {
      "podid": 1,
      "targeting": [
        {
          "hb_pb": "20.00",
          "hb_pb_cat_dur": "20.00_413_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        },
        {
          "hb_pb": "10.00",
          "hb_pb_cat_dur": "10.00_395_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        },
        {
          "hb_pb": "10.00",
          "hb_pb_cat_dur": "10.00_401_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        }
      ]
    },
    {
      "podid": 2,
      "targeting": [
        {
          "hb_pb": "10.00",
          "hb_pb_cat_dur": "10.00_409_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        },
        {
          "hb_pb": "10.00",
          "hb_pb_cat_dur": "10.00_394_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        },
        {
          "hb_pb": "15.00",
          "hb_pb_cat_dur": "15.00_399_30s",
          "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0"
        }
      ],
      "errors": {
        "openx": [
          {
            "code": 1,
            "message": "The request exceeded the timeout allocated"
          }
        ]
      }
    }
  ]
}

SSAI processing of the response

The SSAI should take the key-values from the response adPods.[].targeting.[]${key} and pass it to the primary ad server as keywords. Because adPods do not have specific targeting, an adPod can target any bid as long as the bid duration matches that of the adPod.

Further Reading:

Prebid Server overview
OpenRTB auction endpoint
Category Translation module
Freewheel module
Ad Pod module