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:
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.
Parameter
Description
Example value
iu
Current ad unit.
This should follow the format:
/network_id/directory/ad_unit
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:
-
section=sports
-
page=golf,tennis
SSB streams
: Encode and concatenate the entire cust_params
value, but do not double-encode.
cust_params=
"section%3Dsports
%26page%3Dgolf%2Ctennis"
Chromecast
:
Encode the values only.
streamRequest.
adTagParameters = {
"cust_params":
"section=sports&
multi=golf%2Ctennis"};
Roku
: Encode and concatenate the entire cust_params
value, but do not double-encode.
request.adTagParameters = "cust_params=
section%3Dsports
%26page%3Dgolf%2Ctennis"
iOS
, and tvOS
: Do not encode anything.
request.adTagParameters = @{
@"cust_params" :
@"section=sports&
multi=golf,tennis"};
Android
: Do not encode anything.
Map<String, String>
adTagParams =
new HashMap<>();
adTagParams.put(
"cust_params",
"ge=0&gr=2");
sz
Overrides the sz
parameter from your default ad tag allowing you to change dynamically for different devices.
Do not include the " v
" after the size.
sz=400x300
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 SSB streams and when using the IMA DAI SDK for Roku
. This 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.
This parameter is not set automatically by the IMA SDK. It needs to be set manually.
This field is required if you use Ad Exchange. Learn more
URL-encoded example: description_url=
http%3A%2F%2Fwww.sample.com
%2Fgolf.html
Non-encoded example: description_url=
http://www.sample.com/
golf.html
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=
12JD92J...
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, or Brightcove, that are integrating with the SDK.
mpt=JWPlayer
mpv
Indicates the version of the partner player. This should only be set if mpt
is also set, and represents the version of the partners player that is integrating with the SDK.
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 break_template_id
parameter.
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 an
parameter is the app name.
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 an
parameter (in the format com.package.publisher
).
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
idtype
is_lat
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. Starting with iOS 14.5, Apple has deprecated the 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.
trt
Designates traffic as purchased or otherwise.
Undefined traffic type: trt=0
Purchased traffic: trt=1
Organic traffic: trt=2
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 2
if continuous play is ON, and 1
if OFF.
This parameter should be left unset if it is unknown.
Continuous play ON: vconp=2
Continuous play OFF: vconp=1
vpa
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.
Autoplay: vpa=auto
Click: vpa=click
vpmute
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.
Muted: vpmute=1
Unmuted: vpmute=0
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
to mark the ad request as non-personalized. Omission of the parameter defaults to personalized ads.
npa=1
omid_p
The OMID partner name parameter accepts a variable
value which indicates the name of the partner integrating OMID measurement, and the partner version.
This parameter is only applicable to publishers wanting Active View measurement when using the Open Measurement SDK (OM SDK). This should not be used when using the IMA SDK as it is set automatically.
To indicate OMID support when using Programmatic Access Library (PAL), you need to use the omidPartnerName
and omidPartnerVersion
APIs to set the partner name and version. When you're not using either PAL or IMA, you must set the omid_p
and sdk_apis
parameters (the supported APIs, which could also include other comma separated APIs).
When using PAL:
request.omidPartnerName = 'examplepartnername' request.omidPartnerVersion = '1.0.0.0'
When not using PAL: omid_p=examplepartnername/1.0.0.0&sdk_apis=7
gdpr
gdpr_consent
See the GDPR
specifications.
givn|paln
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.
You can read more about the value passed to this parameter in the getting started guides for PAL
.
addtl_consent
A list of consented Google Ad Tech Providers that are not registered with IAB.
rdp
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.
sdk_apis
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 is used by publishers that use the Programmatic Access Library (PAL). If you attempt to set values to this parameter while using the IMA SDK, the values will be overridden with the values supported by the IMA SDK.
sdk_apis=2,7,9
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 sid=0
.
sid=123e4567-e89b-12d3
-a456-426614174000
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 Icon
and IconClickFallbackImage
support, as documented in this DAI API guide
.*
WTA is not supported for SSB.
This field is required if you use Ad Exchange. Learn more
* Support for IconClickFallbackImage
is not required, except for on CTV devices.
Supported: wta=1
Unsupported: wta=0
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.
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://www.sample.com/golf.html",
"ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
The adTagParameters
structure using encoded values for HTML5stream requests would be:
{
"tfcd": 1,
"iu": "/987654321/path/to/adunit",
"cust_params": "sport%3Dfootball%26city%3Dnewyork",
"description_url": "http%3A%2F%2Fwww.sample.com%2Fgolf.html",
"ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
The adTagParams
structure using encoded values for Rokustream requests would be:
request.adTagParams="tfcd=1&iu=/987654321/path/to/adunit&cust_params=sport%3Dfootball%26city%3Dnewyork&description_url=http%3A%2F%2Fwww.sample.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
.
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.
Live linear stream examples
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.
