Skip to end of metadata
Go to start of metadata

Long Form Video Service

Long-form video is video with a duration length greater than thirty minutes. Impression bus provides support for displaying ad pods, a set of sequential ads, within a long-form video. The ad pods can be delivered either at pre-roll, mid-roll, or post-roll positions. To initiate an auction for ad pods, publishers submit request parameters via POST in JSON format to the prebid/video endpoint.

On This Page

Request and Response Process

The following steps outline the long-form video request and response process: 

  1. Publishers submit a long-form video request to impbus to the prebid/video endpoint. This request contains POST values for the long-form video ad pod such as ad duration, video width and height, and optional properties such as brand category for competitive separation. 
  2. Impbus unpacks the request and determines the number of ad slots to fill within the ad pod. 
  3. The configurations from the console are retrieved and an OpenRTB request with the requested number of ad slots created by Impbus.
  4. Impbus submits the OpenRTB request to all APN demand partners, including Prebid Server (PBS) and APN Console.
    1. The Prebid demand partners return bids, each with a unique IAB subcategory
    2. The console and external bidders have a unique Xandr brand category associated with every bid. These brand categories are converted to an IAB subcategory.
  5. Impbus runs the auction for the Xandr marketplace to determine the winning Xandr bid.
  6. Based on the publisher and ad server configuration retrieved in step three, i mpbus translates the IAB subcategories to the primary ad server categories (Freewheel or Google Ad Manager).
    1. For Xandr bids, impbus will translate from the Xandr category to the IAB subcategory and finally to the primary ad server category.
  7. The bids are deduped based on the tuple values for price bucket, primary ad server category, and duration.
  8. For each unique bid, impbus caches the unique VAST XML. 
  9. Key-value targeting pairs are generated for each bid for hb_pb, hb_pb_cat_dur,  and  hb_cache_id. 
  10. Impbus returns a JSON response with Prebid targeting key-value pairs and the cache id.

 

Competitive Separation

If competitive separation, the process of preventing two ads from the same industry appearing within an ad pod, is required, Prebid will need to be configured to accept brand category exclusions. After you have instantiated a Prebid instance call the setConfig method and add the following key-values.

REST API

The following table list the required and optional parameters for submitting a long-form video bid request. 

ParameterScopeTypeDescription
appRequired*ObjectContainer object describing the app that will display the ad pod(s). If app is not included in the request then the site parameter must be.
app.domain
RequiredStringThe domain of the app.
app.nameOptionalStringThe name of the app.
app.bundleOptionalStringA platform-specific application identifier intended to be unique to the app and independent of the exchange. This should be a bundle or package name (e.g., com.foo.mygame).
bcatOptionalString[]Blocked advertiser categories using the IAB content categories. 
badvOptionalString[]Blocked list of advertisers by their domains  (e.g., “ford.com”). 
cacheconfig.ttl 
OptionalIntegerTime to live for a cache entry specified in seconds
cacheconfig.disablecache 
OptionalBooleanThe default setting is false. If this flag is set, the PBS cache is disabled and the responsibility of caching is on the publisher or publisher's vendor. See the Disable Cache section for more details.
contentOptionalObject Container object describing miscellaneous content metadata that can be used for targeting the adPod(s)
content.episodeOptional IntegerThe episode number.
content.titleOptionalString 

The episode title.

content.season Optional StringThe episode season name.
content.seriesOptional StringThe series name.
content.lenOptional IntegerThe length of the episode in seconds.
content.livestreamOptionalInteger

The content mode indicator for VOD or Live. Accepted values are:

 0. Not live,

  1. Content is live (e.g., stream, a live blog).
deviceOptionalObjectContainer object describing the device being used for video rendering.
device.ua 

Optional

 StringThe browser user agent.
device.dnt 
OptionalInteger

The standard “Do Not Track” flag as set in the header by the browser. Accepted values are:

 0. Tracking is unrestricted.

  1. Do not track.
device.lmt 
OptionalInteger

The “Limit Ad Tracking” signal for mobile devices (e.g., iOS, Android). Accepted values are:

0. Tracking is unrestricted.

  1. Tracking must be limited per commercial guidelines.
device.ip 

Optional

StringThe IP address of the device making the ad request.
device.os 
OptionalStringThe device operating system. Example "iOS".
device.h 
OptionalIntegerThe physical height of the screen in pixels.
device.w 
OptionalIntegerThe physical width of the screen in pixels.
device.devicetype 

Optional

Integer

The general type of device. Accepted values are:

  • Mobile/Tablet 
  • Personal Computer 
  • Connected TV 
  • Phone 
  • Tablet 
  • Connected Device 
  • Set Top Box
device.ifa 

Optional

StringThe ID sanctioned for advertiser use in the clear (i.e., not hashed).
device.didsha1

Optional

StringThe hardware device ID (e.g., IMEI); hashed via SHA1.
device.didmd5 

Optional

StringThe hardware device ID (e.g., IMEI); hashed via MD5.
device.dpidsha1 

Optional

StringThe platform device ID (e.g., Android ID); hashed via SHA1.
device.dpidmd5 

Optional

StringThe platform device ID (e.g., Android ID); hashed via MD5.
device.macsha1 

Optional

StringThe MAC address of the device; hashed via SHA1.
device.macmd5 

Optional

StringThe MAC address of the device; hashed via MD5.
includebrandcategoryOptionalObjectContainer object describing brand category inputs.
includebrandcategory.primaryadserverOptional  Integer

 An integer whose value represents the ad server used by the publisher. Accepted values are:

  1. Freewheel
  2. Google Ad Manager
memberid Optional
(Required if using inventory codes)
IntegerThe seller's member id.
podconfig
RequiredObjectContainer object for describing all the pod configurations. See the Pod section for more information on the pod object.
podconfig.durationrangesec
Required[Integer]Range of ad durations allowed in the response. See Duration Range section for more detail on duration range. 
podconfig.requireexactduration
OptionalBooleanFlag indicating if submitted ads must meet the exact duration requirement. The default setting is false.
pricegranularity
Optional (recommended)ObjectFor more information on the pricegranualrity object see the Price Granularity section. For a broader explanation on setting price granularity see the Prebid documentation.
siteRequiredObjectContainer object describing the page submitting the adpod request. If site is not included then the app parameter must be.
site.page
RequiredStringA URL of the page where the impression will be displayed.
userOptionalObjectContainer object describing the user of the device.
user.buyeruid
Optional Integer The AppNexus user id. For more information see the Buyer UID section.
user.yobOptionalIntegerThe user's year of birth as a four-digit integer.
user.genderOptionalInteger

The user's gender. Accepted values are:

  • M: male
  • F: female
  • O: Known to be other.
user.keywordsOptionalStringA list of keywords representing interests or intent.
user.gdprOptionalObjectContainer object describing the user's GDPR settings. For more information see the GDPR section below.
videoRequiredObjectContainer object describing the video player.
video.wOptionalIntegerThe width of the video player in device independent pixels
video.hOptionalIntegerThe height of the video player in device independent pixels
video.mimesRequired[String]An array of video player supported mime types. Example: ["video/mp4"]
video.protocolsRequired[String]

An array of video protocols supported by the video player. Accepted video protocols are:

  • VAST 1.0
  • VAST 2.0
  • VAST 3.0
  • VAST 1.0 Wrapper
  • VAST 2.0 Wrapper
  • VAST 3.0 Wrapper
  • VAST 4.0
  • VAST 4.0 Wrapper
  • DAAST 1.0
  • DAAST 1.0 Wrapper



Pods

parameterScopeTypeDescription
podconfig.pods
RequiredObject[]Container object for describing the adPod(s) to be requested.
pod.podid 
RequiredIntegerUnique id of the pod within a particular request. It is recommended these be ordered sequentially with an increment of one.
pod.adpoddurationsec  
RequiredIntegerThe duration of the adPod.
pod.placementid 
RequiredIntegerPlacement ID that a pod relates to. If placementid is omitted then invcode and request.memberid are required.
pod.invcode 
OptionalStringInventory code that a pod relates to. If the  invcode  is passed in, then the seller must also pass in their member ID in  request.memberid. If invcode is omitted then placementid is required.


Duration Range

The podconfig.durationrangesec is an array of integers representing the ad slot durations within the ad pod:

If requireexactduration is set to false, then the ad's duration will be rounded up to the closest value in the durationrangesec array. The minimum bid duration is zero. Using the setting above, a 10-second bid would be rounded to fifteen seconds and an 18-second bid rounded to thirty.

if 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 example above, an ad submitted with a duration of fifteen seconds would be allowed, whereas an ad submitted with an 18-second duration would be rejected.


Buyer UIDs

buyeruids
 
ScopeTypeDescription
user.buyeruid

Optional

Integer

Container objects for describing the SSP UserIDs to send to the SSPs endpoint. This should be the Xandr UID, which will be mapped to the corresponding demand partner's UID based on our server side user syncing. The user ids are for bidders that are supported by Prebid Server. Format the buyeruid as follows:

Currently supported bidder names are: 

  • 33across
  • Adform
  • AdKernelAdn
  • AppNexus
  • Adtelligent
  • Audience Network
  • Beachfront
  • BrightRoll
  • Conversant
  • E-Planning
  • Grid
  • GumGum
  • iX
  • LifeStreet
  • OpenX
  • PubMatic
  • PulsePoint
  • Rubicon
  • RhythmOne
  • Sonobi
  • So Mo Audience
  • Sovrn
  • Yieldmo

General Data Protection Regulation (GDPR)

GDPR is a data privacy law enacted by the European Union. The goal of GDPR is to provide more stringent data privacy and security measures and more user-friendly disclosures and reporting on data protection practices. 

Parameter ScopeTypeDescription
user.gdpr
OptionalObjectContainer object describing the GDPR settings.
gdpr.consentrequired
OptionalBooleanFlag indicating if GDPR is in effect.
gdpr.consentstringOptionalStringA string, comprised of a series of numbers, which identifies the consent status of an ad tech vendor.



Price Granularity

ParameterScopeTypeDescription
pricegranularity.rangeOptionalObjectContainer object describing the price granularity range.
pricegranularity.range.maxOptionalIntegerThe maximum length of the range.
pricegranularity.range.increment
OptionalFloatThe amount to increment through the range.

Response

Demand partners will return a response to the ad pod bid request in JSON format. 

ParameterTypeDescription
adpods
[Object]Container object describing the Prebid demand partner responses for each ad pod sent in the original request.
adpods[...].podidIntegerThe id of the corresponding ad pod.
adpods[...].targeting[Object]Container object describing the prebid demand partner bids for this pod translated into targeting keys. See the table below for more detail on the adpods.targeting object.
ParameterTypeDescription
adpods[...][].targeting
        
  
adpods[...]targeting.hb_pb The price bucket targeting key. The price bucketing model is defined by the pricegranularity from the request and configuration. The price bucket targeting key-value represents the rounded bid price.
adpods[...]targeting.hb_pb_cat_dur
 

The value of this key represents the concatenation of three values, the price bucket (see adpods[...]targeting.hb_pb), the creative category code, and the duration of the video creative. For example:

This would indicate a price bucket of $12.00 (if the currency was in US dollars), a category code of 135 (in the primary ad server's domain, such as Freewheel or Google Ad Manager), and a duration of thirty seconds.

This key-value must be unique across all bids corresponding to its corresponding ad pod. If there are two identical hb_pb_cat_dur values, impbus will eliminate one of the bids.

adpods[...]targeting.hb_cache_id 

The Prebid cache id. This value maps to the rendered video content.

This key-value must be unique across all bids across  all pods in a single request. The actual creative cache key will be a concatenation of this value and hb_pb_cat_dur. Since hb_pb_cat_dur must be unique across all bids this guarantees that the actual creative cache key will be unique. The actual cache key will be created using macros, as illustrated below:

The hb_cache_id value will be the same for every entry in targeting[...] in a single response.

 

Example