VAST ad tag URL parameters

A VAST ad tag is used by a player to retrieve video and audio ads. To assemble a VAST ad tag URL using the correct parameters, refer to the table below. Once you've assembled the URL, you can test it with the VAST suite inspector.

VAST ad tags support both https and http URLs. Impression and VAST tracking URLs respect the SSL setting and return either https or http, as appropriate. Click-through and click-tracking are 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.

Ad tag URLs for audio ads must contain the ad_type parameter set to either audio or audio_video for audio ads to serve.

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

You can also review and test using these sample tags.

Index of parameter types and requirements

Required parameters with constant values

The following parameters are required for all VAST ad tag URLs. Each of these parameters has a constant value. For example, the env parameter set to vp indicates that the request is from a video player.

env
gdfp_req
unviewed_position_start

Required parameters with variable values

The following parameters are required for all VAST ad tag URLs. These parameters have variable values. Refer to the description and sample values for guidance.

correlator
description_url
iu
output
sz
url

Optional parameters

The following parameters are optional. These parameters have variable values. Refer to the description and sample values for guidance.

aconp
ad_rule
ciu_szs
cmsid | vid
cust_params
hl
msid | an
nofb
pp
ppid
rdid | idtype | is_lat
rdp
tfcd
npa
vconp
vpa
vpi
vpmute

Custom SDK parameters

The following parameters are the defaults set by the Google IMA SDK. Only include the parameters below in your VAST ad tag URL if you're not using the IMA SDK.

The current Ad Manager architecture requires that video ad requests include information about ads previously shown in the stream and on the page. This information helps build a picture of past activity while accounting for ad exclusions and duplicates.

afvsz
excl_cat
lip
max_ad_duration | min_ad_duration
mridx
pmad
pmnd | pmxd
pod
ppos
sid
scor
vad_type
vpos
wta
ParameterDescriptionRequirement
env

(Environment)

Indicates an instream 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.


For example:

Video and/or audio:
env=instream

Video only:
env=vp

Required

gdfp_req

(Ad Manager schema indicator)

Indicates that the user is on the Ad Manager schema.


For example:

gdfp_req=1

Required

unviewed_position_start

(Delayed impressions)

Setting this to 1 turns on delayed impressions for video.


For example:

unviewed_position_start=1

Required

output

(Ad output format)

Output format of ad.

Use output=vast for the VAST version you have enabled for your network (for example, VAST 4). For specific ad tags or parts of your site, you can explicitly ask for VAST 3 with output=xml_vast3 or VMAP 1 with output=xml_vmap1.

Note that 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 enabled for your network (for example, VMAP 1). If you're returning VAST inside of VMAP, you can use xml_vmap1_vast3 or xml_vmap1_vast4 to specify the VAST version to return.


For example:

vast (for your network's default VAST setting)
xml_vast3 (for VAST 3)
xml_vast4 (for VAST 4)

vmap (for you network's default VMAP setting)
output=xml_vmap1 (for VMAP1)
xml_vmap1_vast3 (for VMAP1, returning VAST3)
xml_vmap1_vast4 (for VMAP1, returning VAST4)

Required

iu

(Ad unit)

Current ad unit.

Follows the format:
/network_id/.../ad_unit


For example:

iu=/6062/videodemo

Required

sz

(Size)

Size of master video ad slot. Multiple sizes should be separated by the pipe (|) character.

Do not include "v" after the size.


For example:

sz=400x300

Required
(Optional if only requesting "ad_type=audio")

description_url

(Description URL)

The value should describe the video playing on the page. Usually, it's the page that houses the video player, but could also be a page with text that describes the video.*

You must always url-encode description_url on web page video players.

This field is required if you use Ad Exchange. Learn more

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


For example:

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

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

Required

url

(URL)

This is the full URL from which the ad request is being sent. On a web page, this is the URL of the page that displays the video player. In an app, this is the package name.*

If you use the IMA SDK, it sets the URL value automatically. If your player sets this value, the IMA SDK overwrites it and set its own value.

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


For example:

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

Required

correlator

(Correlator)

A random positive numerical value that is shared by multiple requests coming from the same page view.

The correlator is 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 IMA SDK overwrites it with its own random value.

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


For example:

correlator=4345645667

Required

aconp

(Continuously play audio)

Recommended per MRC Audio Measurement Guidelines

Indicates whether the player intends to continuously play audio content.

Possible values are 2 if continuous play is ON, and 1 if OFF.

This parameter should be left unset if it is unknown.


For example:

Continuous play ON:
aconp=2

Continuous play OFF:
aconp=1

Optional

ad_rule

(Ad rule)

Indicates whether to return a VAST creative or an ad rules response. If you are using ad rules, then ad_rule=1 should be used. Other requests should use ad_rule=0 (or simply exclude the parameter).

Learn more about ad rules.


For example:

ad_rule=0 indicates a request for a creative (VAST)

ad_rule=1 indicates a request for an ad rules (VMAP)

Optional

ad_type

(Ad type)

Indicates the type of ad that should be returned for the request.*

Possible values are audio to only return an audio ad, video to only return a video ad, or audio_video to return either (while this allows both formats to compete, only one ad is served).

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


For example:

Return an audio ad:
ad_type=audio

Return an audio or video ad:
ad_type=audio_video

Must be passed for audio ads

ciu_szs

(Companion sizes)

Comma-separated list of companion sizes.

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


For example:

ciu_szs=728x90,300x250

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

Optional

cmsid
vid

(Content source ID, video ID)

In order to target ads to video content, your master video tag needs to include both cmsid and vid.  

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 content source.

The vid is a string or number identifying a particular piece of video content. 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 content from the list.


For 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 cmsid and vid.

For example:

cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%

Optional

cust_params

(Custom key-value parameters)

See examples of how to add key‑value pairs.

Optional

hl

(Language)

The language code used to request ads in that language.

This parameter is used for language of ad selection and video ad rendering in dynamic allocation to video in Ad Exchange or AdSense Video.

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

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


For example:

hl=it

Optional

msid
an

(App ID and name)

The msid parameter is the app ID and the an parameter is the app name.

Both parameters 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).


For example:

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

Optional

nofb

(Fallback disabled)

Indicates whether your ad request should not return a playlist of "video fallback" ads.

Learn more about video fallback.


For example:

nofb=1

Optional

pp

(Video and audio creative profile)

Control which creatives are eligible to serve based on the configuration set up in a video and audio creative profile.

Learn more about creative profiles.


For example:

pp=creative_profile

Optional

ppid

(Publisher Provided Identifier)

The Publisher Provided Identifier (PPID) allows publishers to send an identifier for use in frequency capping, audience segmentation and targeting, sequential ad rotation and other audience-based ad delivery controls across devices.

Learn more


For example:

ppid=12JD92JD8078S8J29SDOAKC0EF230337

Optional

rdid
idtype
is_lat

(Resettable device identifiers)

With native 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 Video Solutions ad request. Learn more

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 publisher's 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.

 


See detailed examples of resettable device identifiers.

Optional

rdp

(Restrict data processing)

Tags an ad request to
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.


For example:

rdp=1

Optional

tfcd

(Child-directed treatment)

Tags an ad request for child-directed treatment. 

Learn more about tfcd.


For example:

tfcd=1

Optional

npa

(Non-personalized ad)

Tags an ad request 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.

Learn more about ad personalization.


For example:

npa=1

Optional

vconp

(Continuously play video)

Recommended per MRC Video Measurement Guidelines

Indicates whether the player intends to continuously play video content, similar to a TV broadcast.

Possible values are 2 if continuous play is ON, and 1 if OFF.

This parameter should be left unset if it is unknown.


For example:

Continuous play ON:
vconp=2

Continuous play OFF:
vconp=1

Optional

vpa

(Video play automatic)

Recommended per MRC Video Measurement Guidelines

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.


For example:

Autoplay:
vpa=auto

Click to play:
vpa=click

Optional

vpi

(Video playlist inred)

Indicates whether to serve inline VMAP (return VAST inside of VMAP).

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

Possible values are 1 to return VAST, and 0 (or unset) to return redirect tags.


For example:

Return VAST:
vpi=1

Return redirects:
vpi=0

Optional

vpmute

(Video play mute)

Recommended per MRC Video Measurement Guidelines

Indicates whether the ad playback starts while the video player is muted.

Possible values are 1 for muted, and 0 for unmuted.

This parameter should be left unset if it is unknown.


For example:

Muted:
vpmute=1

Unmuted:
vpmute=0

Optional

afvsz

(Non-linear ad sizes)

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, populated with all supported sizes that fall within the nonLinearAdSlotWidth and nonLinearAdSlotHeight.


For 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

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

pod

(Pod number)

Represents a pod within a video. Pass pod=1 for first pod, pod=2 for second pod, and so on. Used for competitive exclusions, frequency capping, and related features.


For example:

pod=3

Must be passed for features such as competitive exclusions, frequency capping, and related features to work correctly.

ppos

(Position in pod)

Represents position within a pod. Necessary for companion autofill. Pass &ppos=1 for the first position, &ppos=2 for the second position, and so on. Used for competitive exclusions, frequency capping, and related features.

This parameter is for standard pods only.


For example:

ppos=2

Must be passed for features such as competitive exclusions, frequency capping, and related features to work correctly.

vpos

(Pre-roll, mid-roll, or post-roll)

Indicates whether the ad request is being sent from pre-roll, mid-roll or post-roll.


For example:

vpos=preroll
vpos=midroll
vpos=postroll

Optional

mridx

(Mid-roll number)

Number-based index that indicates from which mid-roll a request is made (1st, 2nd, 3rd, etc.)


For example:

mridx=2

Optional

lip

(Last position in standard pod)

Needs to be added for a request from the last position in a pod.

This parameter is for standard pods only.


For example:

lip=true

Required for standard pods

min_ad_duration
max_ad_duration

(Duration of ad)

Taken together, these specify the duration range that an ad must match, in milliseconds.

Used to request a single ad.


For example:

min_ad_duration=15000&max_ad_duration=30000

Optional

pmnd
pmxd

(Duration of pod)

Taken together, these specify the duration range that a pod must match, in milliseconds.

Used to request multiple ads (i.e., pods).

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


For example:

pmnd=0&pmxd=60000

Required for optimized pods

pmad

(Pod ad maximum)

Max number of ads in a pod.

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


For example:

pmad=4

Optional

excl_cat

(Exclusion category)

Blocks any line items containing the exclusion label in question from being eligible for a given ad request; works with cust_params.


For example:

&custom_params=excl_cat
%3Dairline_excl_label%7C

Optional

scor

(Video stream unique number)

An integer generated for each video stream; the number needs to be the same within a stream and unique within a page view. Used for competitive exclusions, frequency capping, and related features if a user is watching multiple videos on the same page.


For example:

scor=17

Must be passed for features such as competitive exclusions, frequency capping, and related features to work correctly.

sid

(Session ID)

A type of privacy-safe advertising identifier that can be used for frequency capping purposes only. Per the IAB's IFA guidelines, this parameter should be populated in UUID format. Learn more


For example:

123e4567-e89b-12d3-a456-426614174000

Must be passed for features such as competitive exclusions, frequency capping, and related features, to work on CTV/OTT platforms when PPID or other user IDs (typically RDID on CTV/OTT) are not present in the request, or when "Limit Ad Tracking" (LAT) is enabled for a user (is_lat=1).

vad_type

(Linear or non-linear ad)

Indicates whether a linear or non-linear ad should be returned for the request.


For example:

vad_type=linear
vad_type=nonlinear

Optional

wta

(Why this ad?)

Indicates the video player's support for rendering "Why this Ad?".

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

This field is required if you use Ad Exchange. Learn more

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.


For example:

Supported:
1

Unsupported:
0

Must be set accurately if you use Ad Exchange.