Supplying any of the following targeting parameters is optional.
When you create or configure a content source for video on demand (VOD) or set up a live stream for DAI, you need to specify a default video ad tag. All DAI streams use that ad tag and its parameters by default. Ad tag parameters apply to both mid-rolls and pre-rolls. If you want your player to request something unique for a given stream, these options are available to you.
Ad Manager ad tag parameters that can be overridden
Jump to a specific parameter:
addtl_consent an ciu_szs cust_params description_url gdpr gdpr_consent idtype is_lat |
iu ltd mpt mpv npa ppid ptpl ptpln rdid |
rdp sid sz tfcd trt vconp vpa vpmute wta |
Override the default ad tag
When your video player requests a stream, the default ad tag is used exactly as you have specified it in the interface. However, you have the ability to override certain parameters of that tag in your stream request. These are the only parameters that can be overridden.
Learn how to override the default ad tag using the IMA SDK or using SSB.
Parameter | Description | Example value | |
---|---|---|---|
iu |
Current ad unit. This should follow the format: |
iu=/6062/video/example_unit |
|
cust_params |
Key-value pairs that should be used for Ad Manager campaign targeting. Some platforms require URL encoding. The URL encoding requirement does not apply when using the IMA DAI SDK for HTML5, as the value is automatically encoded. This parameter will not work if it is already encoded on HTML5. |
Examples with multiple key-value pairs, such as:
SSB streams: Encode and concatenate the entire
Chromecast:
Roku: Encode and concatenate the entire
iOS, and tvOS: Do not encode anything.
Android: Do not encode anything.
|
|
sz |
Overrides the Do not include the " |
sz=400x300 |
|
tfcd |
Tag a request for child-directed treatment. When a DAI request includes |
|
|
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. This parameter is not set automatically by the IMA SDK. It needs to be set manually. |
URL-encoded example: Non-encoded example: |
||
ppid |
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 | ppid= |
|
ciu_szs |
Comma-separated list of companion ad sizes. Companion ads are only supported with DAI when you use the HTML5 SDK. |
ciu_szs=728x90,300x250 |
|
mpt |
Indicates the name of the partner player. This would mostly be used by partners like JWPlayer, Brightcove, Ooyala that are integrating with the SDK. |
mpt=JWPlayer |
|
mpv |
Indicates the version of the partner player. This should only be set if |
mpv=2.1 |
|
ptpl |
The ad break template ID.
You can find this ID in the Ad Manager URL when viewing the settings for the break template in the Ad Manager interface. It appears as the value for the |
ptpl=1234 |
|
ptpln |
The ad break template name. This corresponds to the "Name" field in Ad Manager, not the diplay name.
|
ptpln=my_break_template |
|
an |
The It should be applied to requests sent from mobile app and connected TV devices, as most programmatic video ads require it.* The IMA SDK will automatically populate this, but it must be manually specified with DAI API and SSB (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 SDK sends the app bundle via the |
|
|
ltd |
Indicates whether to serve ads in a limited way in the absence of consent for the use of cookies or other local identifiers. Learn more | ltd=1 |
|
rdid |
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.
|
See detailed examples of resettable device identifiers. | |
trt |
Designates traffic as purchased or otherwise. |
Undefined traffic type: Purchased traffic: Organic traffic: |
|
vconp |
Recommended per MRC Video Measurement Guidelines
Indicates whether the player intends to continuously play the content videos one after another, similar to a TV broadcast. Possible values are This parameter should be left unset if it is unknown. |
Continuous play ON:vconp=2 Continuous play OFF: |
|
vpa |
Recommended per MRC Video Measurement Guidelines
Indicates whether the ad starts through autoplay or click. Possible values are This parameter should be left unset if it is unknown. |
Autoplay:vpa=auto Click: |
|
vpmute |
Recommended per MRC Video Measurement Guidelines
Indicates whether the ad playback starts while the video player is muted. Possible values are This parameter should be left unset if it is unknown. |
Muted:vpmute=1 Unmuted: |
|
npa |
The personalization setting for ad requests. You should specify the parameter early in the tag to avoid any risk of truncation.
Specify |
npa=1 |
|
gdpr gdpr_consent |
These fields are used to pass TCF v2.0 consent information for both in-bound and out-bound cookie sync requests. |
See the GDPR specifications. |
|
addtl_consent |
A list of consented Google Ad Tech Providers that are not registered with IAB. |
See the Additional Consent specifications. |
|
rdp |
You must either specifically set |
|
|
sid |
A type of privacy-preserving advertising identifier that can be used for frequency capping purposes only. Per the IAB's IFA guidelines, this parameter must be populated in UUID format. Learn more You can opt out of passing the session ID by setting |
|
|
wta |
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 WTA is not supported for SSB. This field is required if you use Ad Exchange. Learn more * Support for |
Supported: Unsupported: |
Override the default ad tag using the IMA SDK
When a video player requests a DAI stream using the IMA SDK, it can pass in a field called "adTagParameters
". This dictionary-like structure can be set with key-value pairs where the keys may be the Ad Manager ad tag parameters listed in the table above.
You can customize your stream and pass in parameters which are not related to the Ad Manager ad request using this same structure. Learn how to request specific stream variants and how to set up an ad holiday.
The implementation of the adTagParameters
field is slightly different depending on the specific programming language or platform. See the iOS, Android, tvOS, Chromecast, HTML5 development documentation or additional documentation in the DAI player and app development guide.
Set adTagParameters through the SDK
When you set cust_params
or description_url
through the SDK, on iOS, tvOS, and Android apps, you should not url-encode the strings. You can pass the cust_params
through as a single string that concatenates the key-value pairs with a "&
".
For example, if you wanted to set cust_params
to the value of sport=football&city=newyork
:
The adTagParams
structure using non-encoded values would be:
{
"tfcd": 1,
"iu": "/987654321/path/to/adunit",
"cust_params": "sport=football&city=newyork",
"description_url": "http://sample.com/golf.html",
"ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
The adTagParameters
structure using encoded values for HTML5 stream requests would be:
{
"tfcd": 1,
"iu": "/987654321/path/to/adunit",
"cust_params": "sport%3Dfootball%26city%3Dnewyork",
"description_url": "http%3A%2F%2Fsample.com%2Fgolf.html",
"ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
The adTagParams
structure using encoded values for Roku stream requests would be:
request.adTagParams="tfcd=1&iu=/987654321/path/to/adunit&cust_params=sport%3Dfootball%26city%3Dnewyork&description_url=http%3A%2F%2Fsample.com%2Fgolf.html&ppid=12JD92JD8078S8J29SDOAKC0EF230337"
Override the default ad tag using the DAI API (Beta)
When a video player requests a DAI stream using the DAI API, it can optionally pass key-value pairs, where the keys may be the Ad Manager ad tag parameters listed in the table above.
These parameters should be sent as part of the HTTP POST request body, of form type application/x‑www‑form‑urlencoded
for both linear/live and VOD.
You can customize your stream and pass in parameters which are not related to the Ad Manager ad request using this same structure. Learn how to request specific stream variant parameters, and HMAC authentication.
See a DAI API sample implementation.
Override the default ad tag using SSB
The following are examples of modifying an SSB default VOD ad tag. Overwritten parameters passed by the player or app are highlighted.
Video on demand examples |
Example | |
---|---|
Base VOD stream URL | http://dai.google.com/ondemand/hls/content/ |
(with an ad unit specified) | http://dai.google.com/ondemand/hls/content/ |
(with overridden key-values) |
http://dai.google.com/ondemand/hls/content/ |
(with a declaration of child-directed content) |
http://dai.google.com/ondemand/hls/content/ |
(with an over-ridden ad unit AND key-values AND a custom description_url AND a declaration of child-directed content) |
http://dai.google.com/ondemand/hls/content/ |
Live linear stream examples |
Example | |
---|---|
Base live linear stream URL | https://dai.google.com/linear/hls/event/<asset_key> |
(with an ad unit specified) | https://dai.google.com/linear/hls/event/<asset_key> |
(with over-ridden key-values) | https://dai.google.com/linear/hls/event/<asset_key> |
(with a declaration of child-directed content) |
https://dai.google.com/linear/hls/event/<asset_key> |
(with an overridden ad unit AND key-values AND a custom description_url AND a declaration of child-directed content) |
https://dai.google.com/linear/hls/event/<asset_key> |
Dynamically update targeting parameters during a specific live stream
You can dynamically update the targeting data for a specific user in the middle of watching the stream using the replaceAdTagParameters method in the IMA DAI SDK.