Supply targeting parameters to your stream

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 givn|paln idtype is_lat iu

iu is_lat ltd mpt mpv npa omid_p ppid ptpl ptpln rdid rdid

rdp sdk_apis 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: /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
tfcd	Tag a request for child-directed treatment. When a DAI request includes tfcd=1, any values assigned to the rdid, idtype, or is_lat parameters are removed to comply with COPPA.	tfcd=1
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 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, Brightcove, Ooyala 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).	an=sample%20app
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.	See detailed examples of resettable device identifiers.
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 omidPartnerVersionAPIs to set the partner name and version. When you're not using either PAL or IMA, you must set theomid_pandsdk_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	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.
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.	See the Additional Consent specifications.
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.	rdp=1
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.

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://www.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%2Fwww.sample.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%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.

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/ <contentid>/vid/<vid>/master.m3u8
(with an ad unit specified)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?iu=/9876/ path/to/adunit
(with overridden key-values)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8& cust_params=sport%3Dgolf%26section%3Dblog %26anotherKey%3Dvalue1%2Cvalue2
(with a declaration of child-directed content)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?tfcd=1
(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/ <contentid>/vid/<vid>/master.m3u8& iu=/9876/path/to/adunit& cust_params=sport%3Dgolf%26section %3Dblog%26anotherKey%3Dvalue1%2Cvalue2& description_url=https://mysite.com/description.html& tfcd=1

 

Live linear stream examples

	Example
Base live linear stream URL	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8
(with an ad unit specified)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?iu=/9876/path/to/adunit
(with over-ridden key-values)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?cust_params=sport%3Dgolf%26section %3Dblog%26otherKey%3Dvalue1%2Cvalue2
(with a declaration of child-directed content)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?tfcd=1
(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> /master.m3u8& iu=/9876/path/to/adunit& cust_params=sport%3Dgolf%26section%3Dblog%26otherKey %3Dvalue1%2Cvalue2& description_url=https://mysite.com/description.html& tfcd=1

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.

For any issues related to DAI troubleshooting or outages, contact publisher support.