Video-specific Parameters

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. 

This parameter is mandatory for video and audio ads serving through VAST.

placementHighly Recommended

Placement type for the impression. Use 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).
rewardOptional

The 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
  • 3 - video/wmv
  • 4 - video/h264
  • 5 - video/webm
  • 6 - application/javascript (VPAID - JS)
  • 7 - video/ogg
  • 9 - video/3gpp 
  • 10- video/quicktime 
  • 11- video/mpeg 
  • 12- application/x-mpegURL

For example: 1+5+6+7

 Its default value is 0 (All).  If you include values 2 or 6 in vfmt, you must include the corresponding vapi parameter (VPAID version) as well.

vapiMandatory
Video ad API (VPAID) version supported as per the IAB standards in response. Possible options are:
  • 2 - VPAID 2.0
  • 7 - OMID-1  (Open Measurement)

If you include a VPAID version, you must also include a corresponding VPAID mime type in the vfmt parameter; for example, application/javascript.

vadFmt

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

This parameter maps to the oRTB parameter, video.protocols.

vplayHighly recommended
List 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

You can use the vplay parameter to set the start volume for PubMatic's VPAID player if no other methods are available. See, Understanding VPAID Sound Behavior.

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 recommended

Position of the video in the content. Possible options are:

  • 0 - Any position
  • 1 - Pre-roll
  • 2 - Mid-roll
  • 3 - Post-roll

The default value for vpos is 0. This parameter maps to the oRTB parameter video.startdelay.

vcomHighly recommended

Indicates whether a companion ad is requested or not. Possible options are:

  • 0 - False
  • 1 - True

Default value: 0.

vcomwHighly recommendedWidth (in pixels) of the companion ad. Default value: 300.
vcomhHighly recommendedHeight (in pixels) of the companion ad. Default value: 250.
vcontHighly recommendedContextual information about the web page serving the ad. Partner-dependent data that may be encoded and passes to the demand side for Brand Safety and/or used internally for blocking lists.
vtypeHighly recommended

Linearity type. Possible values are:

  • 0 - Any type
  • 1 - Linear
  • 2 - Overlay (Non-linear)

Default value: 0.
vskipdelayNon-mandatory

Duration (in seconds) after which the user can skip the video ad, when ad is skippable. After the skip-delay (also known as skip-offset) duration, a skip button appears which lets the user skip the unplayed portion of the ad. Possible value is any positive integer.

Default value: 0 (indicates that users can skip the ad immediately).
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

Publishers can use this parameter to provide the flexibility for advertisers to play a non-skippable video ad in skippable ad inventory (a 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)

Use the player's API (if available) to get this value.

vclnNon-mandatory

Language used for player control or user interaction. Values will be passed using the alpha-2/ISO 639-1 standard.

Use the player's API (if available) to get this value.

kadwidthNon-mandatory

Width (in pixels) of the video ad; for example, 640.

If kadwidth = null, then the PubMatic passes the value of adtype instead.

kadheightNon-mandatory

Height (in pixels) of the video ad; for example, 480.

If kadheight = null, then the PubMatic passes the value of adtype instead.

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

Determines whether the video player receives the PubMatic JavaScript VPAID component. PubMatic VPAID components manage ads, report on granular error codes, and manage third-party performance. 

Possible values include: 

  • 1 - Video player receives only the PubMatic JavaScript VPAID component

  • null - PubMatic VPAID component is returned in the response
devicetypeMandatory for CTV publishers

Flags the target platform to receive impressions for Connected TV. Currently, the only value for this parameter is 3.

vfullscreenexpandableNon-mandatory

Identifies whether or not the ad is expandable to fullscreen, or unknow. 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
cntidstring128 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).
cnturtstring32 bytesUser 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

cntgenstring64 bytesGenre of video content
cntpronamestring64 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