VAST ad tag URL parameters

VAST ad tag URL parameters

A VAST ad tag URL is used by a player to retrieve video and audio ads. You can manually assemble a VAST ad tag URL or modify an existing URL using the parameters below, and then test with the VAST suite inspector. You can also review and test using these sample tags.

VAST ad tags support both http and https. Impression tracking URLs respect the current SSL setting and return as either http or https. Click-through and click-tracking use http since they redirect from another page.

Ad tag URLs for live stream video must contain /live in their path to ensure the ability to handle heavy traffic volumes, where all ad breaks are delivered at the same time.

Example

A sample VAST ad tag URL, with parameters and assigned values would look something like this:

https://securepubads.g.doubleclick.net/gampad/ads?env=vp&gdfp_req=1&output=vast&iu=/1234/video-demo&sz=400x300&unviewed_position_start=1&ciu_szs=728x90,300x250

Jump to a specific parameter in the list

aconp
ad_rule
ad_type
afvsz
allcues
an
ciu_szs
correlator
cmsid
cust_params
description_url
env
excl_cat
gdfp_req
hl

idtype
ipe
is_lat
iu
lip
ltd
max_ad_duration
min_ad_duration
mridx
msid
nofb
npa
output
pmad

pmnd
pmxd
pod
pp
ppid
ppos
rdid
rdp
scor
sdk_apis
sid
ssss
sz
tfcd
unviewed_position_start

url
vad_type
vconp
vid
vid_d
vpa
vpi
vpmute
vpos
wta

 
Parameter Details
aconp

(Audio continuous play)

Recommended per MRC Audio Measurement Guidelines

The audio continuous play parameter accepts a constant value that indicates whether the player intends to continuously play audio content.

This parameter should be left unset if it's not known.

Usage example

Continuous play ON:
aconp=2

Continuous play OFF:
aconp=1

ad_rule

(Ad rule)

The ad rule parameter accepts a constant value that indicates whether to return a VAST creative or an ad rules response.

Usage example

Request for VAST creative:
ad_rule=0 (or simply exclude the parameter)

Request for ad rules (VMAP):
ad_rule=1

Requirement

Required for video ad rules

ad_type

(Ad type)

The ad type parameter accepts a constant value which indicates the type of ad that should be returned for the request.

This parameter is currently not required to only return a video ad.

Usage example

Return only an audio ad:
ad_type=audio

Return only a video ad:
ad_type=video

Return either an audio or video ad:
ad_type=audio_video

(This value allows both formats to compete, but only one serves)

Requirement

Required for audio ads

afvsz

(Non-linear ad sizes)

The non-linear ad sizes parameter accepts constant values which should be a comma-separated list of non-linear ad sizes that can be displayed in the video ad slot.

These sizes must be any of the those supported:

  • 200x200
  • 250x250
  • 300x250
  • 336x280
  • 450x50
  • 468x60
  • 480x90
  • 729x90

When using the IMA SDK, this field will be overwritten and populated with all supported sizes that fall within the nonLinearAdSlotWidth and nonLinearAdSlotHeight.

This parameter can be left out or empty when no non-linear sizes are supported.

Usage example

All sizes are supported:
afvsz=200x200,250x250,300x250,336x280,
450x50,468x60,480x90,728x90

Max width is 250:
afvsz=200x200,250x250

Max height is 60:
afvsz=450x50,468x60

Max width is 100:
//empty; no values supported

 

Requirement

Required for non-linear video ads when not using the IMA SDK

allcues

(All cue points)

This parameter accepts variable values which are a comma-separated list of cue points, in milliseconds. For each value, Ad Manager returns an ad break.

The vid_d and allcues parameters are used to serve mid-roll ads without content ingestion. Ad rules are also required to return mid-rolls.

If time-based cues are used in your ad rules (for example, "Every N seconds" or "At fixed times"), then those set in the ad rule are used, and the cues passed into allcues are ignored. Mid-rolls still require duration, so vid_d must still be passed.

Usage example

Cue points at 10 and 20 seconds:
allcues=10000,20000

ciu_szs

(Companion sizes)

The companion sizes parameter accepts variable values which are a comma-separated list of companion sizes.

Pipe-separated (|) values indicate a multi-size ad slot.

Usage example

ciu_szs=728x90,300x250

Sizes with a multi-size slot:
ciu_szs=728x90,300x200|300x250

cmsid
vid

(Content source ID, video ID)

The content source ID and video ID parameters accept variable values. 

In order to target ads to video content, your master video tag needs to include both of these parameters.

The cmsid is a unique number for each content source. To locate this in Ad Manager, click Video and then Content sources and then the name of the source.

The vid is a string or number identifying a particular video. This ID is assigned by the CMS that hosts your content. To locate this in Ad Manager, click Video and then Content and then the specific video content.

Usage example

cmsid=[value]&vid=[value]

If you are building a tag for Dynamic Ad Insertion with video on demand, you should use the macros that will dynamically insert the correct content source and video ID. 

For example: cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%

Requirement

Required for video content targeting

correlator

(Correlator)

The correlator parameter accepts a variable value that is shared by multiple requests coming from the same page view. It's used to implement competitive exclusions, including those in cookieless environments.

If the IMA SDK is used, the correlator value is set automatically. If your player attempts to set this value, the SDK overwrites it with its own value.

If the IMA SDK is not used, ensure that you set this value to a truly random, positive, numerical value that is not being reused by multiple page views.

Usage example

correlator=4345645667

Requirement

Required for web and app

Recommended for Programmatic monetization

cust_params

(Custom key-value parameters)

The custom parameters parameter accepts variable values which are key-value pairs that allow you to set specific targeting, such as demographics, certain positions on a page, or a particular page or pages.

Usage example

See examples of how to add key‑value pairs.

description_url

(Description URL)

The description URL parameter accepts a variable value that should describe the video playing on the page. Usually, it's the page with the video player, but could also be a page with text that describes the video.

The description_url value must be URL-encoded for web page video players and CTV/OTT devices and non-encoded for mobile in-app video players.

This parameter is not set automatically by the IMA SDK. It needs to be set manually.

Usage example

URL-encoded:
description_url=https%3A%2F%2Fwww.sample.com%2Fgolf.html

Non-encoded:
description_url=https://www.sample.com/golf.html

Requirement

Required for webapp, and Ad Exchange

env

(Environment)

The environment parameter accepts a constant value that indicates an in-stream request, or that the request is specifically from a video player.

Possible values are instream, which can be used for video and audio ads, or vp which can only be used for video ads.

Usage example

Video and/or audio:
env=instream

Video only:
env=vp

Requirement

Required for web and app

excl_cat

(Exclusion category)

The exclusion category parameter accepts variable values and is used to block any line items containing the exclusion label in question from being eligible for a given ad request. This parameter works with cust_params.

Usage example

&cust_params=excl_cat%3Dairline_excl_label%7C

gdfp_req

(Ad Manager schema indicator)

The Ad Manager schema indictor parameter accepts a constant value which indicates that the user is on the Ad Manager schema.

Usage example

gdfp_req=1

Requirement

Required for web and app

hl

(Language)

The language parameter accepts a constant value which is used to request ads in that language, and for language of ad selection and video ad rendering in dynamic allocation to Ad Exchange or AdSense Video.

The parameter value can be any ISO 639-1 (two-letter) or ISO 639-2 (three-letter) code. See a list of valid codes.

If omitted, the value defaults to any language with ad targeting by language in Ad Exchange.

Usage example

hl=it

Requirement

Recommended for Programmatic monetization

ipe

(Impression pinging entity)

The impression pinging entity parameter accepts a constant value which is used to indicate impression pings and conversions that originate from the server, not the client.

Usage example

Server-side beaconing (SSB):
ipe=ssb

iu

(Ad unit)

The ad unit parameter accepts a variable value which should be set to the current ad unit, in the format:

/network_id/.../ad_unit

Usage example

iu=/6062/videodemo

Requirement

Required for web and app

lip

(Last position in pod)

The last position in pod parameter accepts a constant value to indicate a request from the last position in a pod.

This parameter is for standard pods only.

Usage example

lip=true

ltd

(Limited ads)

The limited ads parameter accepts a constant value which indicates whether to serve ads in a limited way in the absence of consent for the use of cookies or other local identifiers.

Usage example

ltd=1

min_ad_duration
max_ad_duration

(Ad duration)

The ad duration parameters accept variable values which, taken together, specify the duration range that an ad must match, in milliseconds.

This parameter is used to request a single ad.

Usage example

min_ad_duration=15000&max_ad_duration=30000

mridx

(Mid-roll number)

The mid-roll number parameter accepts a variable value which indicates the ordinal number of the mid-roll (for example, mid-roll 1, mid-roll 2, etc.).

Usage example

mridx=2

msid
an

(App ID and name)

The app ID and name parameters accept variable values which should be applied to requests sent from mobile app and connected TV devices, as most programmatic video ads require them.

The IMA SDK will automatically populate both parameters, but they must be manually specified in direct VAST calls (non-SDK environments).

While the app name should be a human-readable name, on iOS and tvOS, it's not possible for the SDK to access the 9-digit App Store ID. In these cases, the msid parameter is not sent, and the SDK sends the app bundle via the an parameter (in the format com.package.publisher).

Usage example

msid=com.package.publisher an=sample%20app

Requirement

Required for app

Recommended for Programmatic monetization

nofb

(Fallback disabled)

The fallback disabled parameter accepts a constant value to indicate that the ad request should not return a playlist of video fallback ads.

Usage example

Fallback disabled:
nofb=1

npa

(Non-personalized ad)

The non-personalized ads parameter accepts a constant value to indicate that the ad request should be treated as non-personalized.

You must either specifically set npa=1 or include simply npa (without a set value) to tag the request as non-personalized. Ad requests either missing this parameter, or set to npa=0, default to personalized ads.

Usage example

Non-personalized ads:
npa=1

output

(Ad output format)

The ad output format parameter accepts a constant value which should be set to the output format of ad.

Use output=vast for the default VAST version set for your network. For specific ad tags or parts of your site, you can request specific VAST or VMAP versions.

For VAST, if your video player uses the IMA SDK, the output parameter for a video ad request will always be set to output=xml_vast4. This poses no reliability risk as the SDK is backwards compatible with all VAST versions that any third-party ad server may serve.

Use output=vmap to return the default VMAP version you have activated for your network (for example, VMAP 1). If you return VAST inside of VMAP, you can use xml_vmap1_vast3 or xml_vmap1_vast4 to specify the VAST version to return.

Usage example

Your network's default VAST setting:
output=vast

VAST 4:
output=xml_vast4

Your network's default VMAP setting:
output=vmap

VMAP 1:
output=xml_vmap1

VMAP 1, returning VAST 4:
output=xml_vmap1_vast4

Requirement

Required for web and app

pmad

(Pod maximum ads)

The pod ad maximum parameter accepts a variable value which indicates the maximum number of ads in a pod.

This parameter is specific to optimized pods, which are available to publishers with an advanced video package. It should not be used for VMAP (when ad_rule=1).

Usage example

pmad=4

pmnd
pmxd

(Pod duration)

The pod duration parameters accept variable values which, taken together, specify the duration range that a pod must match, in milliseconds.

These parameters are used to request multiple ads. They're specific to optimized pods, which are available to publishers with an advanced video package. They should not be used for VMAP (when ad_rule=1).

Usage example

pmnd=0&pmxd=60000

pod

(Pod number)

The pod number parameter accepts a variable value which represents the ordinal number of the pod in a video (for example, pod 1, pod 2, etc.).

Usage example

pod=3

Requirement

Required for competitive exclusions, frequency capping, and related features to work correctly.

pp

(Creative profile)

The creative profile parameter accepts a variable value which controls the creatives eligible to serve based on the configuration set up in a video and audio creative profile.

Usage example

pp=creative_profile

Requirement

Recommended for Programmatic monetization

ppid

(Publisher provided identifier)

The Publisher provided identifier (PPID) parameter accepts a variable value of the identifier is used in frequency capping, audience segmentation and targeting, sequential ad rotation, and other audience-based ad delivery controls across devices.

Usage example

ppid=12JD92JD8078S8J29SDOAKC0EF230337

ppos

(Position in pod)

The position in pod parameter accepts a variable value which represents the position within a pod (for example, position 1, position 2, etc.).

This parameter is for standard pods only and is necessary for companion autofill.

Usage example

ppos=2

Requirement

Required for competitive exclusions, frequency capping, and related features to work correctly.

rdid
idtype
is_lat

(Resettable device identifiers)

The resettable device identifiers accept variable values.

With built-in applications (not on web or mobile web), the SDK passes resettable device identifiers for user targeting into your stream requests with the parameters for rdid, idtype, and is_lat. On SSB streams, you must pass these as explicit parameters, just as you would on a client-side ad request. Learn more about device identifiers.

Nearly all programmatic video ads require the presence of these values.

Starting with IOS14, Apple has deprecated the LAT signal, so the default to opt-out is disabled. Where publishers have confirmed, Google instead relies on the presence of a non-zero IDFA to indicate tracking has not been disabled. As such, a valid UserAgent indicating the correct OS version is required.

Usage example

See detailed examples of resettable device identifiers.

Requirement

Required for app

Recommended for Programmatic monetization

rdp

(Restrict data processing)

The restrict data processing parameter accepts a constant value to indicate that the ad request should restrict data processing.

You must either specifically set rdp=1 or include simply rdp (without a set value) to restrict data processing. Ad requests either missing this parameter, or set to rdp=0, will not restrict, unless the Restrict Data Processing network setting is enabled.

Usage example

rdp=1

scor

(Stream correlator)

The stream correlator parameter accepts a variable value which should be an integer generated for each video stream. The number should be the same within a stream and unique within a page view. It's used for competitive exclusions, frequency capping, and related features if a user is watching multiple videos on the same page.

Usage example

scor=17

Requirement

Required for competitive exclusions, frequency capping, and related features to work correctly.

sdk_apis

(SDK API framework)

The SDK API framework parameter accepts a comma-separated list of constant integer values which indicate all of the API frameworks that the player supports.

See a list of possible API Framework values.

This parameter support APIs in the Programmatic Access Library (PAL) for publishers not using the IMA SDK. The IMA SDK overrides any values set with the values supported by the IMA SDK.

Usage example

sdk_apis=2,7,9

sid

(Session ID)

The session ID parameter accepts a variable value which is a privacy-preserving advertising identifier that is used for frequency capping purposes only.

Per the IAB's IFA guidelines, this parameter must be populated in UUID format. Learn more about resettable device identifiers for user targeting.

You can opt out of passing the session ID by setting sid=0.

Usage example

123e4567-e89b-12d3-a456-426614174000

Requirement

Recommended for Programmatic monetization

ssss

(Server-side stitching source)

The server-side stitching source parameter accepts a constant value which should be set to a recognized, Google-supplied value for your video stitching technology vendor.

Video stitching technology vendors using server-to-server integrations with Google are given this value from Google and are able to provide it to you. You can reach out to your Google account manager with any questions about the value to set to this parameter.

Usage example

ssss=mystitcher

Requirement

Required for server-side implementations

sz

(Size)

The size parameter accepts a variable value which should be set to the size of master video ad slot.

Multiple sizes should be separated by the pipe (|) character.

Do not include "v" after the size.

Usage example

sz=400x300

Requirement

Required for web and app

This parameter is optional if only requesting ad_type=audio.

tfcd

(Tag for child-directed)

The child-directed parameter accepts a constant value which tags the ad request for child-directed treatment.

Usage example

tfcd=1

unviewed_position_start

(Delayed impressions)

The delayed impressions parameter accepts a constant value to indicate delayed impressions for video.

Usage example

unviewed_position_start=1

Requirement

Required for web and app

url

(URL)

The URL parameter accepts a variable value which should be set to the full URL from which the request is sent. This value is needed to help buyers identify and understand the context of where this request is coming from. To the extent possible, this value should be dynamically populated on the ad request. 

On a web page, this is the URL of the page that displays the video player. If you use the IMA SDK, the URL value is set automatically. If your player sets this value, the IMA SDK overwrites it and set its own value. 

In an app (mobile or CTV), this value should be set to a URL that most accurately represents the video or audio inventory being monetized. For instance, if the user is watching a video within a mobile app that is also available on a desktop equivalent URL.*

Usage example

url=https://www.videoad.com/golf.html

* For apps, if it is not possible to set this parameter to a variable URL value, it's recommended that it be set with the following pattern:
url=<app/bundleid>.adsenseformobileapps.com/

Requirement

Required for web and app

Recommended for Programmatic monetization

vad_type

(Video ad type)

The video ad type parameter accept a constant value which indicates whether a linear or non-linear ad should be returned.

Usage example

Return a linear ad:
vad_type=linear

Return a non-linear ad:
vad_type=nonlinear

vid_d

(Video duration)

This parameter accepts a variable value which specifies the duration of the content, in seconds. 

The vid_d and allcues parameters are used to serve mid-roll ads without content ingestion. Ad rules are also required to return mid-rolls.

Usage example

Video content duration of 90000 seconds (25 hours):
vid_d=90000

vconp

(Video continuous play)

Recommended per MRC Video Measurement Guidelines

The continuous video parameter accepts a constant value which indicates whether the player intends to continuously play video content, similar to a TV broadcast.

This parameter should be left unset if it is unknown.

Usage example

Continuous play ON:
vconp=2

Continuous play OFF:
vconp=1

vpa

(Video play automatic)

Recommended per MRC Video Measurement Guidelines

The video play automatic parameter accepts a constant value which indicates whether the ad starts through autoplay or click.

Possible values are click if the page waits for a user action or auto if the video plays automatically.

This parameter should be left unset if it is unknown.

Usage example

Autoplay:
vpa=auto

Click to play:
vpa=click

Requirement

Recommended for Programmatic monetization

vpi

(Video playlist inred)

The video playlist inred parameter accepts a constant value which indicates whether to serve inline VMAP (return VAST inside of VMAP).

This parameter can be used to reduce latency, and guarantee frequency caps and competitive exclusions across a video stream.

Usage example

Return VAST:
vpi=1

Return redirects:
vpi=0

vpmute

(Video play mute)

Recommended per MRC Video Measurement Guidelines

The muted video parameter accepts a constant value which indicates whether the ad playback starts while the video player is muted.

This parameter should be left unset if it is unknown.

Usage example

Muted:
vpmute=1

Unmuted:
vpmute=0

Requirement

Recommended for Programmatic monetization

vpos

(Video position)

The video position parameter accepts a constant value which indicates whether the ad request is being sent from pre-roll, mid-roll or post-roll.

Usage example

Pre-roll:
vpos=preroll

Mid-roll:
vpos=midroll

Post-roll:
vpos=postroll

Requirement

Recommended for Programmatic monetization

wta

(Why this ad)

The "Why this ad?" parameter accepts a constant value which indicates the video player's support for rendering "Why this Ad?".

The "Why this ad?" functionality is supported automatically when using the IMA SDK. When the IMA SDK is not used, video players must implement VAST Icon and IconClickFallbackImage support, as documented in the IAB VAST standard.

Audio ad requests should send wta=0 for Open Auction and/or if there is no companion slot. The wta parameter can be omitted or set to 1 if a companion slot is provided and all advertiser campaigns with audience targeting provide companions with WTA disclosure.

Usage example

Supported:
wta=1

Unsupported:
wta=0

Requirement

Required for Ad Exchange

Recommended for Programmatic monetization

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue

Search
Clear search
Close search
Google apps
Main menu
Search Help Center
true
148
false