This article shows a list of required and recommended parameters for VAST ad tags used to serve ads in connected TV implementations.
On this page
- Parameters required for ad serving
- Parameters required for programmatic
- Parameters recommended for programmatic
You can review lists for other implementation types or URL requirements for VAST ad tags.
Required and recommended parameters for connected TV
Parameters required for ad serving
correlator (Correlator)
Description
The correlator parameter (correlator) 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.
Usage examples
correlator=4345645667
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home.
SDK usage
- 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, integer value that is not being reused by multiple page views.
env (Environment)
Description
The environment parameter (env) 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 examples
Video and/or audio:
env=instream
Video only:
env=vp
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home.
This parameter is required to accurately report on request type broken down by "Video tag".
gdfp_req (Schema indicator)
Description
The Google Ad Manager schema indicator parameter (gdfp_req) accepts a constant value which indicates that the ad request is for Google Ad Manager inventory.
Usage examples
gdfp_req=1
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home.
iu (Ad unit)
Description
The ad unit parameter (iu) accepts a variable value which should be set to the current ad unit, in the format: /network_code/.../ad_unit.
Usage examples
iu=/6062/videodemo
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home.
output (Output)
Description
The output format parameter (output) accepts a constant value which should be set to the output format of the ad.
Usage examples
Use your network's default VAST version:
output=vast
Use VAST 4 (you can set specific versions for specific tags):
output=xml_vast4
Use your network's default VMAP setting:
output=vmap
Use VMAP 1:
output=xml_vmap1
Use VMAP 1, returning VAST 4 (if you return VAST inside of VMAP):
output=xml_vmap1_vast4
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home. It is required to output the correct ad serving response format.
SDK usage
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.
sz (Size)
Description
The size (sz) 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 examples
Single size:sz=400x300
Multiple sizes:sz=300x250|400x300
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, and digital out-of-home.
This parameter is optional if only requesting ad_type=audio.
url (URL)
Description
The URL parameter (url) 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 web, this is the URL of the page that displays the video player.
- In non-web environments, this 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.*
Note: url differs from description_url in that url refers to the location that an ad request was made from whereas description_url is a web crawlable page that describes the video content.
The value of this parameter should be encoded.
Usage examples
url=https%3A%2F%2Fwww.example.com%2Fvideo.html
* For apps, if it's not possible to set this parameter to a variable URL value, the following pattern is recommended: url=https%3A%2F%2F<app/bundleid>.example.com
Requirements and recommendations
This parameter is required to implement ad serving in web, mobile apps, connected TV, audio, and digital out-of-home.
SDK usage
If you use the IMA SDK, the URL value is set automatically. If your player sets this value, the IMA SDK will respect the value being set.
Parameters required for programmatic
idtype (Device type)
Description
The resettable device identifier parameters (rdid, idtype, is_lat) accept variable values. This value is also known as the identifier for advertising (IFA).
With mobile applications using the IMA SDK for Android or iOS, the IMA SDK passes resettable device identifiers for user targeting into your stream requests with the parameters for rdid, idtype, and is_lat.
When IMA SDK is not used or when server-side beaconing (SSB) is used, you must pass these as explicit parameters. Learn more about device identifiers.
Nearly all programmatic video ads require the presence of these values.
LAT signal. Google instead relies on the presence of a non-zero IDFA to indicate that the user has consented to tracking on versions of iOS that support App Tracking Transparency. As such, a valid UserAgent indicating the correct OS version is required.Usage examples
See detailed examples of resettable device identifiers.
Requirements and recommendations
While these parameters are not required to serve ads to any specific implementation, they are required for programmatic monetization in mobile apps, connected TV, audio, and digital out-of-home.
For web implementations, resettable device identifiers are not used.
SDK usage
While the IMA SDK automatically passes this field, publishers pass these parameters manually when using the PAL SDK.
is_lat (Limit ad tracking)
Description
The resettable device identifier parameters (rdid, idtype, is_lat) accept variable values. This value is also known as the identifier for advertising (IFA).
With mobile applications using the IMA SDK for Android or iOS, the IMA SDK passes resettable device identifiers for user targeting into your stream requests with the parameters for rdid, idtype, and is_lat.
When IMA SDK is not used or when server-side beaconing (SSB) is used, you must pass these as explicit parameters. Learn more about device identifiers.
Nearly all programmatic video ads require the presence of these values.
LAT signal. Google instead relies on the presence of a non-zero IDFA to indicate that the user has consented to tracking on versions of iOS that support App Tracking Transparency. As such, a valid UserAgent indicating the correct OS version is required.Usage examples
See detailed examples of resettable device identifiers.
Requirements and recommendations
While these parameters are not required to serve ads to any specific implementation, they are required for programmatic monetization in mobile apps, connected TV, audio, and digital out-of-home.
For web implementations, resettable device identifiers are not used.
SDK usage
While the IMA SDK automatically passes this field, publishers pass these parameters manually when using the PAL SDK.
ott_placement (Custom formats)
Description
The custom formats parameter (ott_placement) accepts a constant value which indicates a request for a non-in-stream OTT placement.
Placement definitions for the examples below:
- Pause: Out-stream format that appears via an overlay on top of video content when a user pauses content playback.
- Homescreen: Ad that appears on the homescreen of a CTV device or OTT app. This includes masthead, banner, and tile implementations on a homescreen.
- Picture-in-picture: In-stream video ad played in a separate ad video player beside video content. Typically requires squeezing back video content and loading a second video player.
- L-banner: In-stream display ad that involves squeezing back video content and creating an ad around the video. Typically, but not limited to, an L-shaped ad content box.
- Overlay: Any in-stream ad format that appears on top of video content but does not take up the full screen. Can be a display or video ad.
Usage examples
Supported formats and their corresponding avlues:
Pause:
cust_fmt=1
Homescreen:
cust_fmt=2
Picture-in-picture:
cust_fmt=3
L-banner:
cust_fmt=4
Overlay:
cust_fmt=5
Custom/other:
cust_fmt=99
Requirements and recommendations
This parameter is only required for programmatic monetization in web, mobile apps, and connected TV for publishers monetizing non-standard placements on OTT streaming environments.
plcmt (Placement)
Description
The placement parameter (plcmt) accepts a constant value which is used to indicate whether or not the in-stream inventory is declared as "Instream" or "Accompanying" per the guidance in the IAB specifications.
For non-in-stream requests, this is automatically populated for buyers based on the declared inventory format which overrides any in-stream or accompanying declaration.
Usage examples
In-stream request:
plcmt=1
Accompanying content request:
plcmt=2
Requirements and recommendations
This parameter is required for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
rdid (Resettable device identifier)
Description
The resettable device identifier parameters (rdid, idtype, is_lat) accept variable values. This value is also known as the identifier for advertising (IFA).
With mobile applications using the IMA SDK for Android or iOS, the IMA SDK passes resettable device identifiers for user targeting into your stream requests with the parameters for rdid, idtype, and is_lat.
When IMA SDK is not used or when server-side beaconing (SSB) is used, you must pass these as explicit parameters. Learn more about device identifiers.
Nearly all programmatic video ads require the presence of these values.
LAT signal. Google instead relies on the presence of a non-zero IDFA to indicate that the user has consented to tracking on versions of iOS that support App Tracking Transparency. As such, a valid UserAgent indicating the correct OS version is required.Usage examples
See detailed examples of resettable device identifiers.
Requirements and recommendations
While these parameters are not required to serve ads to any specific implementation, they are required for programmatic monetization in mobile apps, connected TV, audio, and digital out-of-home.
For web implementations, resettable device identifiers are not used.
SDK usage
While the IMA SDK automatically passes this field, publishers pass these parameters manually when using the PAL SDK.
vpa (Video play automatic)
Description
The video play automatic (vpa) parameter accepts a constant value which indicates whether video content in an 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 does not change the state of the video player, playback behavior must be handled directly by the video player.
Usage examples
Autoplay:
vpa=auto
Click to play:
vpa=click
This parameter should be left unset if it is unknown.
Requirements and recommendations
This parameter is required for programmatic monetization in web, mobile apps, connected TV, and audio.
This parameter is also recommended per The Media Rating Council (MRC) Video Measurement Guidelines.
vpmute (Video play mute)
Description
The video play mute parameter (vpmute) accepts a constant value which indicates whether the ad playback starts while the video player is muted. This parameter does not change the state of the video player, playback behavior must be handled directly by the video player.
Usage examples
Playback starts muted:
vpmute=1
Playback starts unmuted:
vpmute=0
Requirements and recommendations
This parameter is required for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
This parameter is also recommended per The Media Rating Council (MRC) Video Measurement Guidelines.
Parameters recommended for programmatic
aconp (Audio continuous play)
Description
The audio continuous play parameter (aconp) accepts a constant value that indicates whether the player intends to continuously play audio content. This helps Google Ad Manager select the most suitable ads for the user experience.
Usage examples
Continuous play on:
aconp=2
Continuous play off:
aconp=1
If you don't know whether audio plays continuously, this parameter should be left unset or set to aconp=0.
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
This parameter is also recommended per The Media Rating Council (MRC) Audio Measurement Guidelines.
an (App name)
Description
The app ID parameter (msid) and app name parameter (an) accept variable values which should be applied to requests sent from mobile app and connected TV devices, as most programmatic video ads require them.
While the app name should be a human-readable name, on iOS and tvOS, it's not possible for the SDK to access the app ID. In these cases, the msid parameter is not sent, and the SDK sends the app bundle via the an parameter.
Usage examples
msid=com.package.publisher&an=sample%20app
App IDs are named and formatted differently across different app stores. See the IAB guidelines for app identification, or examples of common unique identifiers.
For platforms where an app store does not exist, the IAB recommends publishers use the following format for store IDs: com.publisher.deviceplatform
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in mobile apps, connected TV, audio, and digital out-of-home.
For brand safety and allowing more transparency to buyers, including the app information is highly recommended.
SDK usage
The IMA SDK will automatically populate both parameters, but they must be manually specified in non-SDK environments, including direct VAST calls, or when using Programmatic Access Library (PAL) or Publisher Authenticated Inventory (PAI).
Note: If the HTML5 IMA SDK is used, then app info is not used.
dth (Device type hint)
Description
The device type hint parameter (dth) accepts a constant value that helps reduce device misclassification, specifically on connected TV and set top box environments.
Device misclassification may result from unintended errors from the publisher or connected TV OEM. This parameter would be used in conjunction with other signals for Google to automatically flag instances where connected TV inventory may be reclassified.
Usage examples
Requests from:
- Feature phone:
dth=1 - Smart phone:
dth=2 - Desktop:
dth=3 - Tablet:
dth=4 - Connected TV:
dth=5 - Game console:
dth=6 - Set top box:
dth=7
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
SDK usage
This parameter is recommended for PAL and PAI (non-SDK) implementations. It is not needed for IMA SDK or DAI SDK.
givn (Video nonce)
Description
For integrations that use the Programmatic Access Library (PAL), the video nonce parameter accepts a variable string value.
The nonce is URL safe—you don't need to URL-encode it.
Note: If you previously provided a nonce using the legacy paln parameter, it is strongly recommended to migrate to the givn parameter and stop sending paln. Do not include both parameters.
Usage examples
Read more about the value passed to this parameter in the getting started guides for PAL.
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
hl (Language)
Description
The language parameter (hl) 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.
Usage examples
Request ads in Italian:
hl=it
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.
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
msid (App ID)
Description
The app ID parameter (msid) and app name parameter (an) accept variable values which should be applied to requests sent from mobile app and connected TV devices, as most programmatic video ads require them.
While the app name should be a human-readable name, on iOS and tvOS, it's not possible for the SDK to access the app ID. In these cases, the msid parameter is not sent, and the SDK sends the app bundle via the an parameter.
Usage examples
msid=com.package.publisher&an=sample%20app
App IDs are named and formatted differently across different app stores. See the IAB guidelines for app identification, or examples of common unique identifiers.
For platforms where an app store does not exist, the IAB recommends publishers use the following format for store IDs: com.publisher.deviceplatform
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in mobile apps, connected TV, audio, and digital out-of-home.
For brand safety and allowing more transparency to buyers, including the app information is highly recommended.
SDK usage
The IMA SDK will automatically populate both parameters, but they must be manually specified in non-SDK environments, including direct VAST calls, or when using Programmatic Access Library (PAL) or Publisher Authenticated Inventory (PAI).
Note: If the HTML5 IMA SDK is used, then app info is not used.
omid_p (OMID partner name)
Description
The OMID partner name parameter (omid_p) accepts a variable value which indicates the name of the partner integrating OMID measurement, and the partner version.
The supported SDK APIs parameter (sdk_apis) accepts variable values which can either be a single or comma-separated list of supported APIs.
These parameters are parts of a set of parameters used for viewability and ad verification.
Usage examples
When not using PAL:
omid_p=examplepartnername/1.0.0.0&sdk_apis=7
See a list of possible API Framework values.
When using PAL:
request.omidPartnerName = 'examplepartnername'
request.omidPartnerVersion = '1.0.0.0'
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, audio, and digital out-of-home.
SDK usage
- This parameter is only applicable to publishers wanting Active View measurement when using the Open Measurement SDK (OM SDK).
- To indicate OMID support when using Programmatic Access Library (PAL), you need to use
omidPartnerNameandomidPartnerVersionto set the partner name and version. When not using the PAL or IMA SDK, you must set theomid_pandsdk_apisparameters. - This should not be used when using the IMA SDK as it is set automatically.
sid (Session ID)
Description
The session ID (sid) parameter accepts a variable value which is a privacy-preserving advertising identifier that is used for frequency capping purposes only.
Session ID is supported for in-stream video requests from connected TVs and on in-stream video inventory from mobile app devices. It is not currently supported for web.
You can opt out of passing the session ID by setting sid=0.
Usage examples
sid=123e4567-e89b-12d3-a456-426614174000
Per the IAB's IFA guidelines, this parameter must be populated in UUID format. Learn more about resettable device identifiers for user targeting.
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is required for programmatic monetization in digital out-of-home.
This parameter is recommended for programmatic monetization in mobile apps, connected TV, and audio.
SDK usage
This parameter is sent automatically by the IMA SDK.
vconp (Video continuous play)
Description
The video continuous play (vconp) parameter accepts a constant value which indicates whether the player intends to continuously play video content, similar to a TV broadcast.
Usage examples
Continuous play ON:
vconp=2
Continuous play OFF:
vconp=1
This parameter should be left unset if it is unknown.
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, and audio.
This parameter is also recommended per The Media Rating Council (MRC) Video Measurement Guidelines.
vid_d (Video duration)
Description
The video duration (vid_d) parameter accepts a variable value which specifies the duration of the content, in seconds.
- The
vid_dandallcuesparameters are used to serve mid-roll ads without content ingestion. - The use of ad rules is 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
allcuesare ignored. Mid-rolls still require duration, sovid_dmust still be passed.
Usage examples
Video content duration of 90000 seconds (25 hours):
vid_d=90000
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, and connected TV.
vpos (Video position)
Description
The video position (vpos) parameter accepts a constant value which indicates whether the ad request is being sent from pre-roll, mid-roll or post-roll.
Usage examples
Pre-roll:
vpos=preroll
Mid-roll:
vpos=midroll
Post-roll:
vpos=postroll
Requirements and recommendations
While this this parameter is not required to serve ads to any specific implementation, it is recommended for programmatic monetization in web, mobile apps, connected TV, and audio.
If ad rules are used, this parameter is not needed as it's automatically added by the ad server.
wta (Why this ad)
Description
The "Why this ad?" parameter (wta) accepts a constant value which indicates the video player's support for rendering ad badging.
Usage examples
If the player should render the AdChoices icon provided in the VAST response, use:
wta=1(or omit thewtaparameter, or passwtawith no value set)Audio requests should use
wta=1if the AdChoices icon provided in the VAST response will be rendered on companions or otherwise provided to the user.
If the player should not render the AdChoices icon provided in the VAST response, use:
wta=0
Requirements and recommendations
While this parameter is not required to serve ads for any specific implementation type, it is recommended for programmatic monetization for web, mobile apps, connected TV, and audio.
When the parameter is used:
&wta=0traffic isn't eligible for certain types of personalization from Google Demand.&wta=0traffic from EEA is not eligible for creatives with ad badging enabled on reservation and publisher-managed Programmatic Guaranteed line items.
Ads must comply with applicable regulatory requirements for ads served in the European Economic Area (EEA). This includes a mechanism for users to report illegal content. Publishers must notify Google of any illegal content reports using the Report Content on Google form.
SDK usage
The ad badging functionality is supported automatically when using the IMA SDK. When the IMA SDK is not used, video players must implement VASTIcon and IconClickFallbackImage support, as documented in the IAB VAST standard.