为视频流提供定位参数

您可以自行决定是否提供以下任意定位参数。

创建或配置视频点播 (VOD) 的内容来源或为 DAI 设置直播活动时，您需要指定默认的视频广告代码。默认情况下，所有 DAI 视频流都使用默认广告代码及其参数。广告代码参数适用于中贴片广告和前贴片广告。如果希望播放器为给定的视频流请求独特的广告，您可使用下面这些选项。

可替换的 Ad Manager 广告代码参数

跳至特定参数：

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

 

替换默认广告代码

当视频播放器请求视频流时，系统会完全按照您在界面中指定的方式使用默认广告代码。不过，您可以在视频流请求中替换该代码的特定参数。您只能替换下面这些参数。

了解如何使用 IMA SDK 或使用 SSB 替换默认广告代码。

参数	说明	示例值
iu	当前的广告单元。 应遵循以下格式： /network_id/directory/ad_unit	iu=/6062/video/example_unit
cust_params	这是 Ad Manager 广告系列定位应使用的键值对。某些平台需要进行网址编码。 使用适用于 HTML5 的 IMA DAI SDK 时，网址编码要求不适用，因为系统会自动对该值进行编码。如果此参数已在 HTML5 中编码，则不会起作用。	多个键值对的示例如下： section=sports  page=golf,tennis   SSB 视频流：对整个 cust_params 值进行编码和串联，但不进行双重编码。 cust_params=   "section%3Dsports   %26page%3Dgolf%2Ctennis"   Chromecast： 仅对相应值进行编码。 streamRequest. adTagParameters = {   "cust_params":   "section=sports&   multi=golf%2Ctennis"};   Roku：对整个 cust_params 值进行编码和串联，但不进行双重编码。 request.adTagParameters =   "cust_params=   section%3Dsports   %26page%3Dgolf%2Ctennis"   iOS 和 tvOS：不对任何内容进行编码。 request.adTagParameters = @{   @"cust_params" :   @"section=sports&   multi=golf,tennis"};   Android：不对任何内容进行编码。 Map<String, String> adTagParams =   new HashMap<>();   adTagParams.put(   "cust_params",   "ge=0&gr=2");
sz	通过替换默认广告代码中 sz 参数，您可以针对不同设备动态更改尺寸。 请勿在尺寸后添加“v”。	sz=400x300
tfcd	将请求标记为面向儿童的内容。 当 DAI 请求包含 tfcd=1 时，分配给 rdid、idtype 或 is_lat 参数的所有值都会被移除，以遵守 COPPA 的规定。	tfcd=1
description_url	此值应能说明在网页上播放的视频的网址。通常是视频播放器所在网页的网址，但也可以是包含视频介绍文字的网页的网址。 使用适用于 Roku 的 IMA DAI SDK 时，您必须始终对 SSB 视频流中的 description_url 进行网址编码。使用适用于 HTML5 的 IMA DAI SDK 时，不需要您进行网址编码，因为系统会自动对该值进行编码。如果此参数已在 HTML5 中编码，则不会起作用。 此参数不是由 IMA SDK 自动设置的，需要手动设置。 如果您使用 Ad Exchange，则必须填写此字段。了解详情	已编码网址示例： description_url= http%3A%2F%2Fwww.sample.com %2Fgolf.html 未编码网址示例： description_url= http://www.sample.com/ golf.html
ppid	通过发布商提供的标识符 (PPID)，发布商可以发送标识符，以便在各种设备上实现频次上限、受众群细分和定位、依序广告轮播以及基于受众群体的其他广告投放控制功能。了解详情	ppid= 12JD92J...
ciu_szs	随播广告尺寸列表（以英文逗号分隔）。 只有在您使用 HTML5 SDK 时，DAI 才支持随播广告。	ciu_szs=728x90,300x250
mpt	指明合作伙伴播放器的名称。主要用于与 SDK 集成的 JWPlayer 或 Brightcove 等合作伙伴。	mpt=JWPlayer
mpv	指明合作伙伴播放器的版本。此参数用于表示与 SDK 集成的合作伙伴播放器的版本；只有在设置了 mpt 时，才能设置该参数。	mpv=2.1
ptpl	广告插播模板 ID。 在 Ad Manager 界面中查看广告插播模板的设置时，您可以在 Ad Manager 网址中找到该 ID。它显示为 break_template_id 参数的值。	ptpl=1234
ptpln	广告插播模板名称。对应于 Ad Manager 中的“名称”字段，而不是显示名。	ptpln=my_break_template
an	an 参数是应用名称。 此参数应该应用于从移动应用和联网电视设备发送的请求，因为大多数程序化视频广告都需要使用它。* 此参数会由 IMA SDK 自动填充，但必须使用 DAI API 和 SSB（非 SDK 环境）手动指定。 *虽然应用名称应该会是易懂的名称，但在 iOS 和 tvOS 上，SDK 却无法获取 9 位数的 App Store ID。在这些情况下，SDK 会通过 an 参数以 com.package.publisher 的格式发送 app bundle。	an=sample%20app
ltd	用于表明：在未就使用 Cookie 或其他本地标识符征得用户同意的情况下，能否通过一种受限的方式投放广告。了解详情	ltd=1
rdid idtype is_lat	对于原生应用（而非网站或移动网站），SDK 会通过以下各项的参数将用于用户定位的可重置设备标识符传递到视频流请求：rdid、idtype 和 is_lat。在 SSB 视频流中，您必须将这些标识符作为显式参数进行传递，就像处理客户端视频广告解决方案广告请求时一样。 从 iOS 14.5 开始，Apple 已弃用 LAT 信号。Google 则改为依靠非零 IDFA 来表明用户已同意在支持应用跟踪透明度的 iOS 版本上进行跟踪。因此，有效的 UserAgent 表示需要提供正确的操作系统版本。	查看可重置的设备标识符 (RDID) 的详细示例。
trt	用于指定流量类型是否为所购。	未定义的流量类型： trt=0 所购流量： trt=1 自然流量： trt=2
vconp	建议使用，请参阅 MRC 视频衡量指南 指明播放器是否会在一个内容视频播放完后继续播放另一个内容视频（类似于电视广播）。 可能的值包括 2（如果开启连续播放）和 1（如果关闭连续播放）。 如果该参数未知，则应使其保持未设置状态。	开启连续播放： vconp=2   关闭连续播放： vconp=1
vpa	建议使用，请参阅 MRC 视频衡量指南 指明广告是会自动播放还是需经点击才能开始播放。 可能的值包括：click（如果网页等待用户操作）或 auto（如果视频自动播放）。 如果该参数未知，则应使其保持未设置状态。	自动播放： vpa=auto   点击后播放： vpa=click
vpmute	建议使用，请参阅 MRC 视频衡量指南 指明是否在视频播放器处于静音状态时开始播放广告。 可能的值的包括 1（设为静音）和 0（不设为静音）。 如果该参数未知，则应使其保持未设置状态。	设为静音： vpmute=1   不设为静音： vpmute=0
npa	广告请求的个性化设置。您应在代码中比较靠前的位置指定该参数，以避免任何截断风险。 指定 npa=1 可将广告请求标记为非个性化广告请求。如果您不指定该参数，系统会默认为投放个性化广告。	npa=1
omid_p	OMID 合作伙伴名称参数接受变量值，以用于指明集成 OMID 衡量功能的合作伙伴的名称以及合作伙伴版本。 此参数仅适用于使用 Open Measurement SDK (OM SDK) 时需要 Active View 衡量功能的发布商。使用 IMA SDK 时，不应使用此参数，因为系统会自动设置它。 如要在使用 Programmatic Access Library (PAL) 时指明 OMID 支持，您需要使用 omidPartnerName 和 omidPartnerVersion API 来设置合作伙伴名称和版本。如果您不使用 PAL 或 IMA，则必须设置 omid_p 和 sdk_apis 参数（受支持的 API，其中可能包括其他以英文逗号分隔的 API）。	使用 PAL 时： request.omidPartnerName = 'examplepartnername' request.omidPartnerVersion = '1.0.0.0' 不使用 PAL 时：omid_p=examplepartnername/1.0.0.0&sdk_apis=7
gdpr gdpr_consent	这些字段用于为入站和出站 Cookie 同步请求传递 TCF v2.0 意见征求信息。	请参阅 GDPR 规范。
givn|paln	对于使用 Programmatic Access Library (PAL) 的集成，视频 Nonce 参数接受变量字符串值。 Nonce 适合包含在网址中，因此您无需对其进行网址编码。 注意：如果您之前使用旧版 paln 参数提供过 Nonce，我们强烈建议您迁移到 givn 参数并停止发送 paln。请勿同时添加这两个参数。	如需详细了解向此参数传递的值，请参阅 PAL 的相关入门指南。
addtl_consent	未向 IAB 注册但已征得用户同意的 Google 广告技术提供商的列表。	请参阅更多意见征求方式规范。
rdp	您必须明确设置 rdp=1 或仅添加 rdp（不设置任何值），才能限制数据处理。缺少此参数或设置了 rdp=0 的广告请求不会限制数据处理，除非启用了限制数据处理这项广告联盟设置。	rdp=1
sdk_apis	SDK API 框架参数接受由以英文逗号分隔的常量整数值构成的列表，这些整数值表示播放器支持的所有 API 框架。 不妨查看一下可能的 API 框架值的列表。 使用 Programmatic Access Library (PAL) 的发布商会使用此参数。如果您在使用 IMA SDK 时尝试为此参数设置值，这些值将被 IMA SDK 支持的值替换。	sdk_apis=2,7,9
sid	一种可保护隐私的广告标识符，只能用于实现频次上限。根据 IAB 的 IFA 指南，此参数必须以 UUID 格式填充。了解详情 如果选择不传递会话 ID，您可以设置 sid=0。	sid=123e4567-e89b-12d3 -a456-426614174000
wta	指明视频播放器对呈现“为什么显示该广告？”的支持能力。 当使用 IMA SDK 时，系统会自动支持此操作。当未使用 IMA SDK 时，视频播放器必须实现 VAST Icon 和 IconClickFallbackImage 支持（如 DAI API 指南中所述）。* SSB 不支持 WTA。 如果您使用 Ad Exchange，则必须填写此字段。了解详情 *不需要 IconClickFallbackImage 支持（除非是在 CTV 设备上）。	支持： wta=1 不支持： wta=0

使用 IMA SDK 替换默认广告代码

视频播放器使用 IMA SDK 请求 DAI 视频流时，可以传递一个称为“adTagParameters”的字段。您可以使用键值对来设置这种字典式结构，其中的键可以是上表中列出的 Ad Manager 广告代码参数。

您可以自定义视频流，并使用同样的结构传入与 Ad Manager 广告请求无关的参数。了解如何请求特定视频流变体以及如何设置暂停显示广告的时长。

adTagParameters 字段的实现因具体的编程语言或平台而略有不同。请参阅 iOS、Android、tvOS、Chromecast、HTML5 开发文档，或 DAI 播放器和应用开发指南中的其他文档。

 

通过 SDK 设置 adTagParameters

在 iOS、tvOS 和 Android 应用中通过 SDK 设置 cust_params 或 description_url 时，不得对字符串进行网址编码。您可以通过一个使用“cust_params”将多个键值对串联到一起的字符串来传递 cust_params。

例如，如果要将 cust_params 设为 sport=football&city=newyork 的值：

使用未经编码的值的 adTagParams 结构如下：

{
  "tfcd": 1,
  "iu": "/987654321/path/to/adunit",
  "cust_params": "sport=football&city=newyork",
  "description_url": "http://www.sample.com/golf.html",
  "ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
 

使用经过编码的值且适用于 HTML5 视频流请求的 adTagParameters 结构如下：

{
  "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"
}
 

使用经过编码的值且适用于 Roku 视频流请求的 adTagParams 结构如下：

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"

使用 DAI API 替换默认广告代码 ^{（Beta 版）} 

视频播放器使用 DAI API 请求 DAI 视频流时，可以选择传递键值对，其中的键可以是上表中列出的 Ad Manager 广告代码参数。

这些参数应作为 HTTP POST 请求正文的一部分发送，并且无论是对于线性/直播还是视频点播，这些参数的格式类型均为 application/x‑www‑form‑urlencoded。

您可以自定义视频流，并使用同样的结构传入与 Ad Manager 广告请求无关的参数。了解如何请求特定的视频流变体参数和 HMAC 身份验证。

请参阅 DAI API 示例实现。

使用 SSB 替换默认广告代码

下面的示例展示了如何修改 SSB 默认 VOD 广告代码。播放器或应用传递的被替换参数会突出显示。

视频点播示例

	示例
基准 VOD 视频流网址	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8
（包含一个指定的广告单元）	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?iu=/9876/ path/to/adunit
（包含被替换的 键值对）	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8& cust_params=sport%3Dgolf%26section%3Dblog %26anotherKey%3Dvalue1%2Cvalue2
（声明为 面向儿童的内容）	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?tfcd=1
（包含一个被替换的广告单元、多个键值对、 一个自定义 description_url， 并声明为面向儿童的内容）	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

 

线性直播视频流示例

	示例
基准线性直播视频流网址	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8
（包含一个指定的广告单元）	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?iu=/9876/path/to/adunit
（包含被替换的键值对）	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?cust_params=sport%3Dgolf%26section %3Dblog%26otherKey%3Dvalue1%2Cvalue2
（声明为 面向儿童的内容）	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?tfcd=1
（包含一个被替换的广告单元、多个键值对、 一个自定义 description_url， 并声明为面向儿童的内容）	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

在特定的直播期间动态更新定位参数

您可以使用 IMA DAI SDK 中的 replaceAdTagParameters 方法，为正在观看相应视频流的特定用户动态地更新定位数据。

对于与 DAI 问题排查或服务中断相关的任何问题，请与发布商支持团队联系。