Page tree

Video-specific Parameters

Page Tree

The following video-specific parameters are supported  only  in GET requests.

For details about GDPR parameters see GDPR Mandatory Parameters.

For details about CCPA parameters see CCPA Mandatory Parameters.

For details about CTV parameters for video ad tags see CTV Parameters.


ParameterRequiredDescription
adtypeMandatory

Type of ad. Possible values are:

  • 13 - For video ad request
  • 14 - For Audio Ad request though VAST
  • Other than 13 - For display ad request. 

Note: This parameter is mandatory for video and audio ad serving through VAST.
placementHighly Recommended

Placement type for the impression. Should be used to distinguish between in-stream and out-stream inventory.

Possible integer values:

  • 1 - In-Stream   (Played before, during or after the streaming video content that the consumer has requested: Pre-roll, Mid-roll, Post-roll).
  • 2 - In-Banner   (Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on  the page for its delivery.)
  • 3 - In-Article    (Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.)
  • 4 - In-Feed       (Found in content, social, or product feeds.)
  • 5 - Interstitial/Slider/Floating     (Covers the entire or a portion of screen area, but is always on screen while displayed - i.e. cannot be scrolled out of view).
reward Optional

Only supported integer value is: reward=1. This optional value causes the request to be treated as a rewarded video request.

Notes:

  • Decoding = atoi()
  • Parameter will be consumed for all platforms.
  • Parameter will be ignored for non-video adtype requests.
  • Supported in both URL QueryString param and PostData param.
  • Translator will not discard/ignore video.skip and related signals for rewarded video requests. It will be ignored at AdServer.
vwMandatoryWidth (in pixels) of the video player. For example, 480
vhMandatoryHeight (in pixels) of the video player. For example, 640 
vminlMandatoryMinimum duration (in seconds) of the video clip.
For example, 10
vmaxlMandatoryMaximum duration (in seconds) of the video clip.
For example, 20
vfmtMandatory

Acceptable video formats (i.e., mime types). It is a combination of the following values separated by +:

  • 0 - All
  • 1 - video/mp4
  • 2 - application/x-shockwave-flash (VPAID - FLASH)
  • 3 - video/wmv
  • 4 - video/h264
  • 5 - video/webm
  • 6 - application/javascript (VPAID - JS)
  • 7 - video/ogg
  • 8 - video/flv (Flash Video)
  • 9 - video/3gpp 
  • 10- video/quicktime 
  • 11- video/mpeg 
  • 12- application/x-mpegURL

For example, 1+5+6+7
Note: Its default value is 0 (All).  If vfmt values 2 or 6 are included, the corresponding vapi parameter (VPAID version) must be included as well.
vapiMandatoryVideo ad API (VPAID) version supported as per the IAB standards in response. Possible options are:
  • 1 - VPAID 1.0
  • 2 - VPAID 2.0

Note:   If a VPAID version is included, a corresponding VPAID mime type must be included in the vfmt parameter, such as application/javascript (6) or application/x-shockwave-flash (2).

vadFmt

MandatoryVideo ad format (VAST version) supported in response. Possible options are:
  • 1 - VAST 1.0 (unsupported)
  • 2 - VAST 2.0 (Wrapper + InLine)
  • 3 - VAST 3.0 (Wrapper + InLine)
  • 4 - VAST 2.0 InLine only
  • 5 - VAST 3.0 InLine only

Note: this parameter maps to the oRTB parameter video.protocols

vplayHighly recommendedList of allowed playback methods. If blank, assume that all are allowed. Possible values are as follows:
  • 1 - Autoplay on Page Load, sound On
  • 2 - Autoplay on Page Load, sound Off
  • 3 - Click-to-play
  • 4 - Mouse-over
  • 5 - Autoplay on Entering Viewport, Sound On
  • 6 - Autoplay on Entering Viewport, Sound Off
For example, 1+3
vskipHighly recommended

Indicates whether the video ad can be skipped or not. Possible options are:

  • 0 - Ads cannot be skipped
  • 1 - Ads can be skipped
Default value: 0
vposHighly recommendedPosition of the video in the content. Possible options are:
  • 0 - Any position
  • 1 - Pre-roll
  • 2 - Mid-roll
  • 3 - Post-roll
Note: Its default value is 0. This parameter maps to the oRTB parameter video.startdelay
vcomHighly recommendedIndicates whether a companion ad is requested or not. Possible options are:
  • 0 - False
  • 1 - True
Note: Its default value is 0.
vcomwHighly recommendedWidth (in pixels) of the companion ad.
Note: Its default value is 300.
vcomhHighly recommendedHeight (in pixels) of the companion ad.
Note: Its default value is 250.
vcontHighly recommendedContextual information about the Web page serving the ad. This partner-dependent data can be encoded and has to be passed to the demand side for Brand Safety or used internally for blocking lists.
vtypeHighly recommendedLinearity type. Possible values are:
  • 0 - Any type
  • 1 - Linear
  • 2 - Overlay (Non-linear)
Note: Its default value is 0.
vskipdelayNon-mandatory

Duration (in seconds) after which the user can skip the video ad, in case the ad can be skipped. After the skip-delay (also known as skip-offset) duration, a skip button will appear allowing the user to skip the ad. Possible value is any positive integer.

Default value: 0 (indicates that the ad can be immediately skipped)
vnoskipadlenNon-mandatory

Length of the video ad for which the skip functionality will not be applicable. If the video ads can be skipped, ads shorter than this length are rendered without a skip button, that is, the skip option is available only on ads longer than this duration

Default value: 0

Note: This parameter can be used by the publisher to give some flexibility to the advertisers to play a non-skippable video ad in skippable ad inventory; (trade-off between video ad and publisher content)
varNon-mandatoryRatio of width to height of the display frame for the video, that is, the aspect ratio. Typically, this ratio is either 16:9 (widescreen) or 4:3 (full screen).
vsmNon-mandatory

Mode which the player will use to resize images and video to fit the display. Possible options are:

  • uniform - Fits the player's dimensions while maintaining the original aspect ratio (black bars)
  • exactfit - Fits the dimensions without maintaining the aspect ratio
  • fill - Stretches and zooms the video to fill the dimensions, while maintaining the aspect ratio
  • none - Displays the actual size of the video file (black borders)

Note: Obtaining this value from the player depends upon the player's API.
vclnNon-mandatory

Language used for player control or user interaction. Values will be passed using the alpha-2/ISO 639-1 standard.
Note: Obtaining this value from the player depends upon the player's API.

kadwidthNon-mandatoryWidth (in pixels) of the video ad.
For example, 640
Note: If this parameter's value is not specified, then this value from adtype is passed.
kadheightNon-mandatoryHeight (in pixels) of the video ad.
For example, 480
Note: If this parameter's value is not specified, then this value from adtype is passed.
vminbtrNon-mandatoryMinimum bitrate (in kbps) allowed for the video stream.
For example, 300
vmaxbtrNon-mandatoryMaximum bitrate (in kbps) allowed for the video stream.
For example, 600
jsNon-mandatory

Indicates whether the video player should only receive one PubMatic VPAID component - JavaScript VPAID or Flash VPAID. PubMatic VPAID components are used to manage ads, report on granular error codes, and for third-party measurement. 

PubMatic VPAID tags return both JavaScript and Flash (swf) VPAID media files. The video player can select which to use. If the player does not support the Flash (.swf) version, the js parameter can be used to indicate that only the JavaScript component should be returned. 


Possible values are:

  • 0 - Video player must only receive PubMatic Flash VPAID component. 

  • 1 - Video player must only receive PubMatic JavaScript VPAID component. 

Note: By default, if this parameter is not present or is empty, both PubMatic VPAID components (JavaScript and Flash, in that order) will be returned in the response.

devicetypeMandatory for CTV publishers

The devicetype parameter designated connected TV as the platform for impressions coming from connected TVs. Possible values are

  • 3 - Connected TV
vfullscreenexpandableNon-mandatory

Possible values:

0 = Not Expandable

1 = Is Expandable

2 = Unknown

GDPR Mandatory Parameters

Use the following parameters if an ad request comes from a GDPR regulated country.


ParameterRequiredDescription
gdprMandatory0=GDPR does not apply
1=GDPR applies
gdpr_consentMandatory

URL-safe base64-encoded GDPR consent string. 

Encodes the consented-to purposes and vendor  consent string , as obtained from the  CMP JS API or OpenRTB.


If you do not include the gdpr_consent string, the video ad request defaults to contextual advertisement. Since PubMatic video tags do not have direct access to the page prior to requesting the video ad, publishers must insert these parameter values during the ad call flow. One way to insert these values is via Key-Value Pairs supported by your video ad server.

CCPA Mandatory Parameters

If publishers are using PubMatic tags to send traffic to PubMatic, and they have traffic from California, then they must pass the CCPA user privacy string in the “us_privacy” parameter for Video tags. 

ParameterRequiredDescription
us_privacyMandatoryccpa us_privacy string for video tags, which contains user optout status.


PubMatic VAST/VPAID Tag Examples:

http://vpaid.pubmatic.com/ads/video/vadtag.html?adtype=13&pubId=12345&siteId=
098765&adId=2345678&vadFmt=2&vapi=1&vminl=5&vmaxl=30&vh=PLAYER_HEIGHT&vw=
PLAYER_WIDTH&placement=1&vtype=1&vpos=1&vplay=2&vskip=0&vcom=1&vcomh=250&
vcomw=300&vfmt=1+5+6+7&sec=1&gdpr=&gdpr_consent=&schain=SUPPLYCHAIN_GOES_HERE&
us_privacy=&kadpageurl=INSERT_ENCODED_PAGEURL_HERE


http://vid.pubmatic.com/AdServer/AdServerServlet?adtype=13&pubId=123456&siteId=
098765&adId=2345678&vadFmt=2&vminl=2&vmaxl=6&vh=PLAYER_HEIGHT&vw=PLAYER_WIDTH&
placement=1&vtype=1&vpos=1&vplay=2&vskip=0&vcom=1&vcomh=250&vcomw=300&vfmt=
1+5+7&sec=1&gdpr=&gdpr_consent=&schain=SUPPLYCHAIN_GOES_HERE&us_privacy=&
kadpageurl=INSERT_ENCODED_PAGEURL_HERE


CTV Parameters

The following parameters can be passed for CTV video ad tags.

The CTV parameters are optional except useragent, useripv4, and useripv6.


Content parameters

Parameter

Data typeLimitsDescription
cntidstring127 byteID uniquely identifying the content.
cntepsint>= 0Episode number
cnttitlestring255 byteContent title. Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web). Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article). 
cntserstring127 byteContent series. Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). Non-Video Example: “Ecocentric” (Time Magazine blog).
cntseastring32 byteContent season (e.g., “Season 3”).
cntpdqint>= 0

Production quality

0 = Unknown

1 = Professionally Produced

2 = Prosumer

3 = User Generated (UGC)

cntctxint> 0Type of content (game, video, text, etc.) Refer to List 5.18 in openRTB 2.5 spec.
cntcrtstring16 byteContent rating (e.g., MPAA).
cnturtstring5 byteUser rating (e.g., "4.5")
cntisliveint>= 00 = not live, 1 = content is live (e.g., stream, live blog).
cntsrcrelint>= 00 = indirect, 1 = direct.
cntlenint> 0Length of content in seconds; appropriate for video or audio.
cntlnstring3 byteContent language using ISO-639-1-alpha-2. (ex: en)
cntisembint>= 0

Indicator of whether or not the content is embeddable (e.g.,

an embeddable video player), where 0 = no, 1 = yes

cntmrtint> 0

Media rating per IQG guidelines.

1 = All Audiences

2 = Everyone Over 12

3 = Mature Audiences

cntgenstring16 bytesGenre of video content
cntpronamestring32 bytesName of producer
cntprodomainstring64 bytesHighest level domain of the content producer (e.g., "producer.com")

Device parameters

ParameterData typeLimitsDescription
makestring32 bytesDevice Make
modelstring32 bytesDevice Model
osstring16 bytesDevice OS
osvstring16 bytesDevice OS version
useragentstring512 bytes

Mandatory

User-agent string

useripv4string46 bytes

Mandatory

IPv4 address closest to the device

useripv6string46 bytes

Mandatory

IP address closest to the device as IPv6

Mobile parameters

For more information about other parameters in the ad tag example below, please refer to Mobile-specific Parameters.

CTV Video Ad Tag Example
Microsoft CTV Site_0x0_Video_CTV_Tag

http://vid.pubmatic.com/AdServer/AdServerServlet?adtype=13&pubId=159173&siteId=
662218&adId=2629420&vadFmt=2&vminl=1&vmaxl=3&vh=PLAYER_HEIGHT&vw=PLAYER_WIDTH&
placement=1&vtype=1&vpos=1&vskip=0&vcom=0&vfmt=1+5+7&sec=1&gdpr=&gdpr_consent=
&schain=SUPPLYCHAIN_GOES_HERE&us_privacy=&useragent=&useripv4=&useripv6=
&authtoken=&api=&bundle=&aid=&name=&storeurl=&carrier=&cat=&city=&cntcrt=
&cntctx=&cnteps=&cntgen=&cntid=&cntisemb=&cntislive=&cntlen=&cntln=&cntmrt=
&cntpdq=&cntprodomain=&cntproname=&cntsea=&cntser=&cntsrcrel=&cnttitle=&cnturt=
&country=&dma=ðn=&kadfloor=&gender=&inc=&keywords=&loc=&make=&model=&nettype=
&os=&osv=&state=&udid=&udidhash=&udidtype=&yob=&zip=&kadpageurl=
INSERT_ENCODED_PAGEURL_HERE

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents