Prebid Server | Endpoints | /openrtb2/video

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

• POST /openrtb2/video
• Overview
  • Process
  • Pod Duration Range
  • Pods
  • Video Protocols
  • Buyer UIDs
  • Price Range
  • Regulations
• Examples
  • Post Request
  • Post Response
• SSAI processing of the response
• Further Reading:

POST /openrtb2/video

Overview

Prebid Server (PBS) supports competitve separation for ad pod display from primary ad servers such as Freewheel and Google Ad Manager. 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

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 and 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:

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.

Buyer UIDs

The user.ext.prebid.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”
• “eplanning”
• “epsilon”
• “grid”
• “gumgum”
• “ix”
• “lifestreet”
• “openx”
• “pubmatic”
• “pulsepoint”
• “rhythmone”
• “rubicon”
• “somoaudience”
• “sonobi”
• “sovrn”
• “yieldmo”

Price Range

The pricegranularity sub-object 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.

Regulations

In order for publishers to meet their transparency, notice and choice/consent requirements under the GDPR and CCPA, Prebid Server supports the IAB Europe Transparency & Consent Framework and the CCPA Compliance Framework.

Publishers can enable GDPR regulations by setting regs.ext.gdpr to 1. To disable GDPR, change the setting to 0. The default setting is 0.

Publishers can comply with CCPA regulations by setting regs.ext.us.privacy to one of the accepted string formats outlined in IAB’s CCPA Framework such as 1YNN.

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": "https://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