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.


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

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.
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.,
bcatOptionalString[]Blocked advertiser categories using the IAB content categories. 
badvOptionalString[]Blocked list of advertisers by their domains  (e.g., “”). 
OptionalIntegerTime to live for a cache entry specified in seconds
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.

The episode title.

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

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. 


 StringThe browser user agent.

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.

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.


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



The general type of device. Accepted values are:

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


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


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


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


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


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


StringThe MAC address of the device; hashed via SHA1.


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.
RequiredObjectContainer object for describing all the pod configurations. See the Pod section for more information on the pod object.
Required[Integer]Range of ad durations allowed in the response. See Duration Range section for more detail on duration range. 
OptionalBooleanFlag indicating if submitted ads must meet the exact duration requirement. The default setting is false.
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.
RequiredStringA URL of the page where the impression will be displayed.
userOptionalObjectContainer object describing the user of the device.
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.

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"]

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


RequiredObject[]Container object for describing the adPod(s) to be requested.
RequiredIntegerUnique id of the pod within a particular request. It is recommended these be ordered sequentially with an increment of one.
RequiredIntegerThe duration of the adPod.
RequiredIntegerPlacement ID that a pod relates to. If placementid is omitted then invcode and request.memberid are required.
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




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
OptionalObjectContainer object describing the GDPR settings.
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

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


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

[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.
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.

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.


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.