本文列出了可在 VAST 广告代码中使用的参数的完整列表。如果您想详细了解某个特定参数,本文可能会对您有所帮助。
查看囊括所有参数的可点击式索引,按字母顺序排列本页内容
按广告实现类型细分的参数列表
如果您使用的是某种特定实现,则可以使用自定义参数列表来概述该实现类型的用法和要求。自定义参数列表适用于:
所有参数
广告投放必需参数
一般来说,大多数广告实现类型都需要使用这些参数才能投放广告。不过,在某些情况下,这些参数可能不是必需的。如需获取最准确的列表,请使用适用于您的具体广告实现类型的参数列表。
correlator
(Correlator)
说明
“Correlator”参数 (correlator
) 接受变量值,源于同一次网页浏览的多项请求会共用此值。在进行竞争排除(包括在没有 Cookie 的环境中)时会用到此参数。
用法示例
correlator=4345645667
description_url
(说明网址)
说明
“说明网址”参数 (description_url
) 接受变量值,此值应用于描述在网页上播放的视频。
说明网址应与网页应用、移动应用或电视应用的特定网页上播放的视频相关。它不应是所有视频或所有广告请求的顶级域名。例如,如果您有一个 https://www.sample.com/golf.html
网页用于展示与高尔夫相关的视频,请将其设置为 description_url
的值。
用法示例
对于包含视频的网页和 CTV/OTT 设备,description_url
值必须经过网址编码。不过,对于移动应用,description_url
值不得编码。
经过网址编码:
description_url=
https%3A%2F%2Fwww.sample.com%2Fgolf.html
未经网址编码:
description_url=
https://www.sample.com/golf.html
要求和建议
若要在网站和移动应用中实现广告投放,则必须提供此参数。如果您使用 Ad Exchange 或 AdSense 进行动态分配,也必须使用此参数。
对于程序化变现,此参数为推荐参数。
SDK 使用情况
此参数不是由 IMA SDK 自动设置的,需要手动设置。
请参阅适用于您平台的 IMA SDK 指南。
env
(环境)
说明
“环境”参数 (env
) 接受常量值,用于指明这是一项插播广告请求或者该请求是明确来自视频播放器。
可能的值包括 instream
(可用于视频和音频广告)或 vp
(仅可用于视频广告)。
用法示例
视频和/或音频:
env=instream
仅限视频:
env=vp
gdfp_req
(架构指示器)
iu
(广告单元)
output
(输出)
说明
“输出格式”参数 (output
) 接受常量值,此值应设为广告的输出格式。
用法示例
output=vast
使用 VAST 4(您可为特定代码设置特定版本):
output=xml_vast4
使用您广告资源网的默认 VMAP 设置:
output=vmap
使用 VMAP 1:
output=xml_vmap1
使用 VMAP 1,返回 VAST 4(如果您在 VMAP 内部返回 VAST):
output=xml_vmap1_vast4
sz
(尺寸)
说明
“尺寸”(sz
) 参数接受变量值,此值应设为主视频广告位的尺寸。
多个尺寸应以竖线 (|
) 字符进行分隔。
请勿在尺寸后面添加“v
”。
用法示例
单个尺寸:sz=400x300
多个尺寸:sz=300x250|400x300
unviewed_position_start
(延迟记录的展示次数)
url
(网址)
说明
“网址”参数 (url
) 接受一个变量值,此值应设为发送请求的完整网址。买方需要使用此值来协助确定和了解该请求是在何种情境下发送的。您应尽可能在广告请求中动态地填充此值。
- 在网站上,这是显示视频播放器的网页的网址。
- 在非网站环境中,此值应设为一个最能准确体现正被用来变现的视频/音频广告资源的网址。例如,如果用户正在一款移动应用内观看某个视频,而等效的桌面版网址上也提供了该视频。*
注意:url
与 description_url
不同,url
是指发出广告请求的位置,而 description_url
是可抓取的网页,用于描述视频内容。
此参数的值应进行编码。
用法示例
url=https%3A%2F%2Fwww.example.com%2Fvideo.html
*对于应用,如果无法将该参数设为一个变量网址值,建议使用以下格式:url=https%3A%2F%2F<app/bundleid>.example.com
vpmute
(视频播放静音)
说明
“视频播放静音”参数 (vpmute
) 接受常量值,用于指明在开始播放广告时是否将视频播放器设为静音状态。此参数不会更改视频播放器的状态,播放行为必须由视频播放器直接处理。
用法示例
播放开始时设为静音:
vpmute=1
播放开始时不设为静音:
vpmute=0
程序化广告必需参数
ott_placement
(自定义格式)
说明
自定义格式参数 (ott_placement
) 接受常量值,用于指明请求非插播 OTT 展示位置。
以下示例的展示位置定义:
- 暂停:用户暂停内容播放时,在视频内容上方以重叠式广告的形式显示的外播广告格式。
- 主屏幕:在联网电视设备或 OTT 应用的主屏幕上展示的广告。这包括主屏幕上的标头广告、横幅广告和功能块植入。
- 画中画:在视频内容旁边的单独广告视频播放器中播放的插播视频广告。通常需要挤回视频内容并加载第二个视频播放器。
- L 型横幅广告:插播展示广告,需要缩小视频内容并在视频周围制作广告。通常是指 L 形广告内容框,但不限于此。
- 重叠式广告:在视频内容上方展示但不会占据全屏的任何插播广告格式。可以是展示广告,也可以是视频广告。
用法示例
支持的格式及其对应的值:
暂停:
cust_fmt=1
主屏幕:
cust_fmt=2
画中画:
cust_fmt=3
L 横幅广告:
cust_fmt=4
重叠式广告:
cust_fmt=5
自定义/其他:
cust_fmt=99
plcmt
(展示位置)
说明
展示位置参数 (plcmt
) 接受常量值,用于指明插播广告资源是声明为插播广告资源还是随播广告资源,详情请参阅 IAB 规范。
对于非插播请求,此字段会由系统根据声明的广告资源格式自动为买家填充,并将替换任何插播或随播声明。
用法示例
插播广告请求:
plcmt=1
随播内容请求:
plcmt=2
venuetype
(场地类型)
说明
场地类型参数 (venuetype
) 用于指明非住宅场地的类型。符合条件的值是 IAB OpenOOH 场地类型 1.1 分类支持的整数枚举 ID。
用法示例
酒店客房:
venuetype=80703
出租车后座上的平板电脑:
venuetype:103
vpa
(视频自动播放)
说明
“视频自动播放”(vpa
) 参数接受常量值,用于指明广告中的视频内容是会自动开始播放还是在用户点击后开始播放。
可能的值包括:click
(如果网页等待用户操作)或 auto
(如果视频自动播放)。此参数不会更改视频播放器的状态,播放行为必须由视频播放器直接处理。
用法示例
自动播放:
vpa=auto
点击播放:
vpa=click
如果该参数未知,则应使其保持未设置状态。
程序化广告建议参数
aconp
(音频连续播放)
说明
“音频连续播放”参数 (aconp
) 接受常量值,用于指明播放器是否会继续播放音频内容。这有助于 Google Ad Manager 选择最适合用户体验的广告。
用法示例
开启连续播放:
aconp=2
关闭连续播放:
aconp=1
如果您不知道音频是否会连续播放,则应使此参数保持未设置状态或将其设置为 aconp=0
。
(应用名称)
说明
“应用 ID”参数 (msid
) 和“应用名称”参数 (an
) 接受变量值,它们应该应用于从移动应用和联网电视设备发送的请求,因为大多数程序化视频广告都需要使用它们。
虽然应用名称应该会是人类可读的名称,但在 iOS 和 tvOS 上,SDK 却无法获取应用 ID。在这些情况下,系统不会发送 msid
参数,而 SDK 会通过 an
参数发送 app bundle。
用法示例
msid=com.package.publisher&an=sample%20app
应用 ID 在不同应用商店中采用不同的命名方式和格式。查看应用识别的 IAB 指南或常见唯一标识符示例。
对于没有应用商店的平台,IAB 建议发布商使用以下格式的商店 ID:com.publisher.deviceplatform
要求和建议
虽然此参数不是向任何特定实现投放广告的必需参数,但对于移动应用、联网电视、音频和数字户外广告中的程序化变现,建议使用此参数。
为保障品牌安全并向买方提供更透明的信息,强烈建议您添加应用信息。
SDK 使用情况
IMA SDK 会自动填充这两个参数,但必须在非 SDK 环境(包括直接 VAST 调用)中或者使用 Programmatic Access Library (PAL) 或发布商身份经过验证的广告资源 (PAI) 时手动指定这些参数。
注意:如果使用 HTML5 IMA SDK,则不会使用应用信息。
dth
(设备类型提示)
说明
设备类型提示参数 (dth
) 接受常量值,有助于减少设备分类错误,尤其是在联网电视和机顶盒环境中。
设备误分类可能是由于发布商或联网电视 OEM 的意外错误造成的。 此参数将与其他信号结合使用,以便 Google 自动标记可能需要对联网电视广告资源进行重新分类的情况。
用法示例
请求来自:
- 非智能手机:
dth=1
- 智能手机:
dth=2
- 桌面设备:
dth=3
- 平板电脑:
dth=4
- 联网电视:
dth=5
- 游戏机:
dth=6
- 机顶盒:
dth=7
givn
(视频 Nonce)
说明
对于使用 Programmatic Access Library (PAL) 的集成,视频 Nonce 参数接受变量字符串值。
Nonce 适合包含在网址中,因此您无需对其进行网址编码。
注意:如果您之前使用旧版 paln
参数提供过 Nonce,我们强烈建议您迁移到 givn
参数并停止发送 paln
。请勿同时包含这两个参数。
用法示例
如需详细了解向此参数传递的值,请参阅 PAL 的相关入门指南。
hl
(语言)
说明
“语言”参数 (hl
) 接受常量值,用于请求使用该语言的广告,在对 Ad Exchange 或 AdSense 视频进行动态分配的过程中,此参数用于指定在进行广告选择和视频广告呈现时所使用的语言。
用法示例
请求以意大利语投放广告:
hl=it
参数值可以是任意的 ISO 639-1(两个字母)或 ISO 639-2(三个字母)代码。请参阅有效代码列表。
如果省略,参数值默认为在 Ad Exchange 中根据语言定位广告时指定的任一语言。
msid
(应用 ID)
说明
“应用 ID”参数 (msid
) 和“应用名称”参数 (an
) 接受变量值,它们应该应用于从移动应用和联网电视设备发送的请求,因为大多数程序化视频广告都需要使用它们。
虽然应用名称应该会是人类可读的名称,但在 iOS 和 tvOS 上,SDK 却无法获取应用 ID。在这些情况下,系统不会发送 msid
参数,而 SDK 会通过 an
参数发送 app bundle。
用法示例
msid=com.package.publisher&an=sample%20app
应用 ID 在不同应用商店中采用不同的命名方式和格式。查看应用识别的 IAB 指南或常见唯一标识符示例。
对于没有应用商店的平台,IAB 建议发布商使用以下格式的商店 ID:com.publisher.deviceplatform
要求和建议
虽然此参数不是向任何特定实现投放广告的必需参数,但对于移动应用、联网电视、音频和数字户外广告中的程序化变现,建议使用此参数。
为保障品牌安全并向买方提供更透明的信息,强烈建议您添加应用信息。
SDK 使用情况
IMA SDK 会自动填充这两个参数,但必须在非 SDK 环境(包括直接 VAST 调用)中或者使用 Programmatic Access Library (PAL) 或发布商身份经过验证的广告资源 (PAI) 时手动指定这些参数。
注意:如果使用 HTML5 IMA SDK,则不会使用应用信息。
omid_p
(Omid 合作伙伴名称)
说明
OMID 合作伙伴名称参数 (omid_p
) 接受变量值,以用于指明集成 OMID 衡量功能的合作伙伴的名称以及合作伙伴版本。
“支持的 SDK API”参数 (sdk_apis
) 接受变量值,这些值可以是单个支持的 API,也可以是逗号分隔的支持的 API 列表。
这些参数是用于衡量广告可见度和进行广告验证的一组参数的一部分。
用法示例
不使用 PAL 时:
omid_p=examplepartnername/1.0.0.0&sdk_apis=7
不妨查看一下可能的 API 框架值的列表。
使用 PAL 时:
request.omidPartnerName = 'examplepartnername'
request.omidPartnerVersion = '1.0.0.0'
要求和建议
虽然此参数不是向任何特定实现投放广告的必需参数,但建议在网站、移动应用、联网电视、音频和数字户外广告中进行程序化创收时使用此参数。
SDK 使用情况
- 此参数仅适用于使用 Open Measurement SDK (OM SDK) 时需要 Active View 衡量功能的发布商。
- 如要在使用 Programmatic Access Library (PAL) 时指明 OMID 支持,您需要使用
omidPartnerName
和omidPartnerVersion
来设置合作伙伴名称和版本。如果您不使用 PAL 或 IMA SDK,则必须设置omid_p
和sdk_apis
参数。 - 使用 IMA SDK 时,不应使用此参数,因为系统会自动设置它。
rdid
(可重置的设备标识符)
说明
可重置的设备标识符参数(rdid
、idtype
、is_lat
)接受变量值。此值也称为广告标识符 (IFA)。
对于使用适用于 Android 或 iOS 的 IMA SDK 的移动应用,IMA SDK 会通过以下各项的参数将用于用户定位的可重置设备标识符传递到视频流请求:rdid
、idtype
和 is_lat
。
如果未使用 IMA SDK 或使用服务器端信标 (SSB),您必须将这些参数作为显式参数传递。详细了解设备标识符。
几乎所有程序化视频广告都需要这些值。
从 iOS 14.5 开始,Apple 已弃用 |
用法示例
查看可重置的设备标识符 (RDID) 的详细示例。
sid
(会话 ID)
说明
“会话 ID”(sid
) 参数接受变量值,它是一种可保护隐私的广告标识符,仅用于实现频次上限。
会话 ID 适用于来自联网电视的插播视频广告请求,以及来自移动应用设备的插播视频广告资源。Web 应用目前不支持此 ID。
如果选择不传递会话 ID,您可以设置 sid=0
。
用法示例
sid=123e4567-e89b-12d3-a456-426614174000
根据 IAB 的 IFA 指南,此参数必须以 UUID 格式填充。详细了解用于用户定位的可重置的设备标识符。
vconp
(视频连续播放)
说明
“视频连续播放”(vconp
) 参数接受常量值,用于指明播放器是否会继续播放视频内容(类似于电视广播)。
用法示例
开启连续播放:
vconp=2
关闭连续播放:
vconp=1
如果该参数未知,则应使其保持未设置状态。
vid_d
(视频时长)
说明
“视频时长”(vid_d
) 参数接受变量值,以用于指定内容的时长(以秒为单位)。
vid_d
和allcues
参数用于在不进行内容提取的情况下投放中贴片广告。- 您必须使用广告规则才能返回中贴片广告。如果您的广告规则中使用了基于时间的广告插入点(例如,“每 N 秒插播一次”或“在固定的时间”),系统会使用广告规则中设定的广告插入点,并忽略传递到
allcues
的广告插入点。插播广告仍需设置时长,因此vid_d
仍是必须传递的参数。
用法示例
视频内容时长为 90000 秒(25 小时):
vid_d=90000
vpos
(视频内位置)
说明
“视频内位置”(vpos
) 参数接受常量值,用于指明广告请求是从前贴片广告位、中贴片广告位还是后贴片广告位发出的。
用法示例
前贴片广告位:
vpos=preroll
中贴片广告位:
vpos=midroll
后贴片广告位:
vpos=postroll
wta
(为什么显示该广告)
说明
“为什么显示该广告?”参数 (wta
) 接受常量值,用于指明视频播放器是否支持呈现广告标示。
用法示例
如果播放器应呈现 VAST 响应中提供的“广告选项”图标,请使用:
wta=1
(或省略wta
参数,或传递未设置值的wta
)如果 VAST 响应中提供的“广告选项”图标将在随播广告上呈现或以其他方式提供给用户,音频请求应使用
wta=1
。
如果播放器不应呈现 VAST 响应中提供的“广告选项”图标,请使用:
wta=0
要求和建议
虽然对于任何特定实现类型而言,无需此参数即可投放广告,但对于网站、移动应用、联网电视和音频中的程序化变现而言,此参数为推荐参数。
使用此参数时:
&wta=0
流量不符合条件,无法使用 Google 需求来源的某些类型的个性化功能。- 来自欧洲经济区 (EEA) 的
&wta=0
流量不符合条件,无法在预订型订单项和由发布商管理的有保证程序化订单项中投放启用了广告标示的广告素材。
广告必须符合在欧洲经济区投放广告需遵循的适用法规要求。这包括为用户提供举报非法内容的机制。发布商必须使用举报 Google 上的内容表单,将收到的所有针对非法内容的举报信息告知 Google。
SDK 使用情况
当使用 IMA SDK 时,系统会自动支持广告标示功能。当未使用 IMA SDK 时,视频播放器必须实现 VASTIcon
和 IconClickFallbackImage
支持,如 IAB VAST 标准中所述。其他参数
一般来说,对于投放广告,不会明确要求使用这些参数,但对于某些功能或某些广告实现类型,可能需要使用这些参数。
ad_rule
(广告规则)
说明
“广告规则”参数 (ad_rule
) 接受常量值,用于指明是返回 VAST 广告素材还是返回广告规则响应。
广告规则的默认设置取决于 Google Ad Manager 广告资源网设置,该设置可将所有请求都设为广告规则请求。如果使用的是广告资源网设置,则无需在广告代码中设置 ad_rule
。如果您想按广告请求进行停用,则可以传递 ad_rule=0
来替换广告资源网设置。此外,如果您默认未启用广告规则,则可以分别传递 ad_rule=1
和 ad_rule=0
来启用/停用广告规则。
用法示例
如果广告规则设置处于停用状态:
- 针对 VAST 广告素材的请求:
ad_rule=0
或不设置
如果广告规则设置处于启用状态:
- 针对 VAST 广告素材的请求:
ad_rule=0
- 针对广告规则 (VMAP) 的请求:
ad_rule=1
或不设置
如果您选择不使用广告规则,则可以使用广告代码参数 pmnd
、pmxd
和 pmad
为 VAST 代码指明广告插播时间点和广告连播时长。
要求和建议
虽然此参数不是任何特定实现类型投放广告的必需参数,但必须提供此参数才能正确使用视频广告规则。
addtl_consent
(更多意见征求方式)
说明
“更多意见征求方式”参数 (addtl_consent
) 接受变量值,适用于以下发布商:想集成 IAB TCF v2.0 且使用尚未注册加入 IAB Europe 全球供应商列表 (GVL) 但已包含在 Google 广告技术提供商 (ATP) 列表中的供应商。
您可在“更多意见征求方式”技术规范中详细了解向此参数传递的值。
用法示例
addtl_consent=1~1.35.41.101
adtest
(广告测试)
说明
应使用广告测试参数 (adtest
),以确保用于测试补余广告(无保证)广告资源的查询不会被识别为无效流量,也不会对收入产生影响。
在测试补余广告时,请将此参数设置为 on
,以确保所有广告都不会记录展示次数或点击次数,以供测试期间使用。在非测试环境中将其设置为 off
,以便正常结算费用。如果未设置,此参数默认为 off
。
注意:测试直销型订单项时,您应改用不会影响收入的测试订单项。
用法示例
开启:
adtest=on
关闭:
adtest=off
ad_type
(广告类型)
说明
“广告类型”参数 (ad_type
) 接受常量值,用于指明应针对该请求返回哪类广告。
当 ad_type
设置为 audio
或 audio_video
时,必须将 vpmute 参数设置为 0
。
用法示例
仅允许投放音频广告:
ad_type=audio
既允许投放可跳过的视频广告,也允许投放不可跳过的视频广告:
ad_type=video
既允许投放音频广告,也允许投放视频广告:
ad_type=audio_video
此
audio_video
值允许这两种格式进行竞争,但只能投放一种。此广告类型仅适用于将视频广告素材投放到支持视频广告播放的音频内容;或者将音频广告素材投放到播放在自然环境中“可听”内容的插播视频广告播放器,例如体育在线播放、视频播报、新闻等。不妨了解视频内容中的音频。
仅允许投放可跳过的视频广告:
ad_type=skippablevideo
仅允许投放不可跳过的视频广告:
ad_type=standardvideo
要求和建议
- 如果您的应用包含视频内容,请将此参数设置为
video
、audio_video
,或不设置此参数。 - 如果您的应用仅包含音频内容(例如电台或语音应用),则必须将此参数设置为
audio
。如果未设置此参数,系统将不会返回任何音频广告。
afvsz
(非线性广告尺寸)
说明
“非线性广告尺寸”参数 (afvsz
) 接受常量值,这些值应为可在视频广告位中展示的非线性广告尺寸的逗号分隔列表。
这些尺寸只能是下列任一受支持的尺寸:
200x200
250x250
300x250
336x280
450x50
468x60
480x90
729x90
当使用 IMA SDK 时,此字段中的值将改为介于 nonLinearAdSlotWidth 和 nonLinearAdSlotHeight 之间所有受支持的尺寸。
如果不支持任何非线性尺寸,则可以省略该参数或将其留空。
用法示例
支持所有尺寸:
afvsz=200x200,250x250,300x250,336x280,
450x50,468x60,480x90,728x90
最大宽度为 250:
afvsz=200x200,250x250
最大高度为 60:
afvsz=450x50,468x60
最大宽度为 100:
//empty; no values supported
要求和建议
虽然此参数对于向任何特定实现或交易类型投放广告而言并非必需,但如果未使用 IMA SDK,则必须使用此参数才能投放非线性视频广告。
allcues
(所有广告插入点)
说明
“所有 cue”参数 (allcues
) 接受变量值,这些值是广告插入点(以毫秒为单位)的逗号分隔列表。对于每个值,Google Ad Manager 都会返回一个广告插播时间点。
vid_d
和allcues
参数用于在不进行内容提取的情况下投放中贴片广告。- 您还需设置广告规则才能返回插播广告。如果您的广告规则中使用了基于时间的广告插入点(例如,“每 N 秒插播一次”或“在固定的时间”),系统会使用广告规则中设定的广告插入点,并忽略传递到
allcues
的广告插入点。插播广告仍需设置时长,因此vid_d
仍是必须传递的参数。
用法示例
将 10 秒处和 20 秒处设为广告插入点:
allcues=10000,20000
ciu_szs
(随播广告尺寸)
说明
“随播广告尺寸”参数 (ciu_szs
) 接受变量值,这些值是随播广告尺寸的逗号分隔列表。
以竖线 (|
) 分隔的值表示多尺寸广告位。
用法示例
ciu_szs=728x90,300x250
多尺寸广告位的尺寸:
ciu_szs=728x90,300x200|300x250
cmsid
(内容来源 ID)
说明
内容来源 ID 参数 (cmsid
) 和视频 ID 参数 (vid
) 接受变量值。
要将广告定位到视频内容,主视频广告代码必须同时包含这两个参数。
cmsid
是每个内容来源的唯一编号。若要在 Google Ad Manager 中找到它,请依次点击视频、内容来源,然后点击相应来源的名称。vid
是用于标识特定视频的字符串或编号。此 ID 由托管内容的 CMS 分配。若要在 Google Ad Manager 中找到它,请依次点击视频、内容,然后点击特定视频内容。
用法示例
cmsid=[value]&vid=[value]
如果您要为包含视频点播内容的动态广告插播构建代码,则应使用可动态插入正确内容来源和视频 ID 的宏。
例如:cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%
要求和建议
虽然这些参数不是投放任何特定实现或交易类型的广告所必需的,但必须使用视频内容定位。
cust_params
(自定义参数)
说明
“自定义参数”参数 (cust_params
) 接受变量值,您可以通过这些键值对来设置具体的定位条件,例如受众特征、网页上的某些位置,或一个或多个特定网页。
用法示例
查看添加键值对的方法示例。
excl_cat
(排除类别)
说明
“排除类别”参数 (excl_cat
) 接受变量值,用于屏蔽广告请求中包含排除标签的所有订单项。使用 cust_params
参数设置排除类别和排除标签。
用法示例
如需为两个排除标签(airline_excl_label
和 train_excl_label
)设置排除类别,请使用竖线字符 (|
) 将标签分隔开来:
excl_cat=airline_excl_label%7Ctrain_excl_label
然后,应用网址编码,并在 cust_params
中使用编码后的字符串:
&cust_params=excl_cat%3Dairline_excl_label%7Ctrain_excl_label
gdpr
(GDPR)
说明
GDPR 参数 (gdpr
) 接受常量值,适用于想集成 IAB TCF v2.0的发布商。直接 VAST 请求不会自动读取这些值,但系统会在这些值添加到广告代码后接受它们。
只有 0
和 1
是此参数的有效值,0
表示 GDPR 不适用,1
表示 GDPR 适用。如果 GDPR 适用,您还必须使用 gdpr_consent 参数提供有效的 TC 字符串。
您可在关于如何实现该框架的通用指南中或在 IAB TCF v2.0 规范的 TC 字符串部分中详细了解向此参数传递的值。
用法示例
GDPR 适用:
gdpr=1
GDPR 不适用:
gdpr=0
gdpr_consent
(GDPR 意见征求)
说明
“依照 GDPR 征求用户意见”参数 (gdpr_consent
) 接受变量值,适用于想集成 IAB TCF v2.0 的发布商。直接 VAST 请求不会自动读取这些值,但系统会在这些值添加到广告代码后接受它们。
您可在关于如何实现该框架的通用指南中或在 IAB TCF v2.0 规范的 TC 字符串部分中详细了解向此参数传递的值。
用法示例
gdpr_consent=GDPR_CONSENT_123
iabexcl
(IAB 排除网址)
说明
IAB 排除网址参数 (iabexcl
) 接受变量值,这些值是逗号分隔的类别列表。
idtype
(设备类型)
说明
可重置的设备标识符参数(rdid
、idtype
、is_lat
)接受变量值。此值也称为广告标识符 (IFA)。
对于使用适用于 Android 或 iOS 的 IMA SDK 的移动应用,IMA SDK 会通过以下各项的参数将用于用户定位的可重置设备标识符传递到视频流请求:rdid
、idtype
和 is_lat
。
如果未使用 IMA SDK 或使用服务器端信标 (SSB),您必须将这些参数作为显式参数传递。详细了解设备标识符。
几乎所有程序化视频广告都需要这些值。
从 iOS 14.5 开始,Apple 已弃用 |
用法示例
查看可重置的设备标识符 (RDID) 的详细示例。
ipd
(广告资源合作伙伴网域)
说明
“广告资源合作伙伴网域”参数 (ipd
) 接受变量值,这些值应设为发布商 app-ads.txt
(或 ads.txt
文件中声明的 inventorypartnerdomain
。
inventorypartnerdomain
参数是一种 IAB 规范,可帮助发布商指定共享广告资源的合作伙伴的网域,以便进行 ads.txt/app-ads.txt
验证。
在广告资源共享用例中,发出广告请求的广告资源可能归其他合作伙伴(共享广告资源的合作伙伴)所有,此时 IPD 声明就尤为重要。
不妨详细了解 ads.txt/app-ads.txt 和共享广告资源的合作伙伴。
用法示例
inventorypartnerdomain
位于 app-ads.txt 文件中,指向可用于变现广告资源的合作伙伴 .txt 文件。ipd
参数中的值应与 app-ads.txt 文件中某个 inventorypartnerdomain
项下的值一致。要求和建议
如果发布商要通过不归其所有的广告资源变现,则必须使用此参数。
ipe
(展示 ping 实体)
说明
“展示 ping 实体”参数 (ipe
) 接受常量值,以用于指明源自服务器(而非客户端)的展示 ping 和转化。
当服务器从服务器发送展示 ping/信标时,就会使用展示 ping 实体。
用法示例
服务器端信标 (SSB):
ipe=ssb
is_lat
(限制广告跟踪)
说明
可重置的设备标识符参数(rdid
、idtype
、is_lat
)接受变量值。此值也称为广告标识符 (IFA)。
对于使用适用于 Android 或 iOS 的 IMA SDK 的移动应用,IMA SDK 会通过以下各项的参数将用于用户定位的可重置设备标识符传递到视频流请求:rdid
、idtype
和 is_lat
。
如果未使用 IMA SDK 或使用服务器端信标 (SSB),您必须将这些参数作为显式参数传递。详细了解设备标识符。
几乎所有程序化视频广告都需要这些值。
从 iOS 14.5 开始,Apple 已弃用 |
用法示例
查看可重置的设备标识符 (RDID) 的详细示例。
lip
(广告连播中的最后一个位置)
说明
“广告连播中的最后一个位置”参数 (lip
) 接受常量值,用于指明从广告连播中的最后一个位置发出的用于定位或报告的请求。
注意:此参数不适用于优化型广告连播,如果使用,系统会忽略此参数。
用法示例
lip=1
ltd
(受限广告)
说明
“受限广告”参数 (ltd
) 接受常量值,用于指明在未就使用 Cookie 或其他本地标识符征得用户同意的情况下,是否要通过一种受限的方式投放广告。
此参数用于指明广告请求受限,不同于 is_lat
参数。它会停用个性化功能,以及停用出于此类目的使用标识符的功能。
ltd=1
会更改 IMA SDK 的行为,以便将相应请求视为不含 ID 并禁止存储。用法示例
ltd=1
max_ad_duration
(广告时长上限)
说明
“广告时长下限”参数 (min_ad_duration
) 和“广告时长上限”参数 (max_ad_duration
) 接受变量值,结合使用此类参数可指定广告的时长范围(以毫秒为单位)。
此参数可用于将广告素材的时长限制为单个广告的广告代码或优化型广告连播请求中所需的时长。
用法示例
min_ad_duration=15000&max_ad_duration=30000
min_ad_duration
(广告时长下限)
说明
“广告时长下限”参数 (min_ad_duration
) 和“广告时长上限”参数 (max_ad_duration
) 接受变量值,结合使用此类参数可指定广告的时长范围(以毫秒为单位)。
此参数可用于将广告素材的时长限制为单个广告的广告代码或优化型广告连播请求中所需的时长。
用法示例
min_ad_duration=15000&max_ad_duration=30000
mridx
(中贴片广告编号)
说明
“中贴片广告位编号”参数 (mridx
) 接受变量值,用于指明中贴片广告位的顺序编号(例如,中贴片广告位 1、中贴片广告位 2 等)。
用法示例
mridx=2
要求和建议
虽然此参数不是向任何特定实现或交易类型投放广告的必需参数,但若要定位到特定中贴片广告、针对中贴片广告生成报告以及针对中贴片广告进行预测,则必须使用此参数。
nofb
(无后备广告)
说明
“无后备广告”参数 (nofb
) 接受常量值,用于指明广告请求不应返回视频后备广告的播放列表。
用法示例
后备广告已停用:
nofb=1
您可以通过传递 nofb=1
,按广告请求停用单个广告后备广告和优化型广告连播候补广告集。
npa
(非个性化广告)
说明
“非个性化广告”参数 (npa
) 接受常量值,用于指明应将广告请求视为非个性化广告请求。
要将相应请求标记为非个性化广告请求,您必须明确设置 npa=1
,或直接添加 npa
(不设置任何值)。缺少此参数或设为 nap=0
的广告请求会默认为请求投放个性化广告。
用法示例
非个性化广告:
npa=1
要求和建议
只有在用户停用个性化设置时,此参数才是必需的。发布商应确保在控制状态时,反映的是用户的准确状态。
ott_placement
(自定义格式)
说明
自定义格式参数 (ott_placement
) 接受常量值,用于指明请求非插播 OTT 展示位置。
以下示例的展示位置定义:
- 暂停:用户暂停内容播放时,在视频内容上方以重叠式广告的形式显示的外播广告格式。
- 主屏幕:在联网电视设备或 OTT 应用的主屏幕上展示的广告。这包括主屏幕上的标头广告、横幅广告和功能块植入。
- 画中画:在视频内容旁边的单独广告视频播放器中播放的插播视频广告。通常需要挤回视频内容并加载第二个视频播放器。
- L 型横幅广告:插播展示广告,需要缩小视频内容并在视频周围制作广告。通常是指 L 形广告内容框,但不限于此。
- 重叠式广告:在视频内容上方展示但不会占据全屏的任何插播广告格式。可以是展示广告,也可以是视频广告。
用法示例
支持的格式及其对应的值:
暂停:
cust_fmt=1
主屏幕:
cust_fmt=2
画中画:
cust_fmt=3
L 横幅广告:
cust_fmt=4
重叠式广告:
cust_fmt=5
自定义/其他:
cust_fmt=99
paln
(Programmatic Access Library Nonce - 旧版)
说明
对于使用 Programmatic Access Library (PAL) 的集成,视频 Nonce 参数接受变量字符串值。
Nonce 适合包含在网址中,因此您无需对其进行网址编码。
注意:如果您之前使用旧版 paln
参数提供过 Nonce,我们强烈建议您迁移到 givn
参数并停止发送 paln
。请勿同时包含这两个参数。
用法示例
如需详细了解向此参数传递的值,请参阅 PAL 的相关入门指南。
pmad
(广告连播中的广告数量上限)
说明
“广告连播中的广告数量上限”参数 (pmad
) 接受变量值,用于指明广告连播中的广告数量上限。
此参数用于限制优化型广告连播中的广告总数。此功能适用于使用高级视频产品包的发布商。
不应将此参数用于 VMAP(当 ad_rule=1
时)。
用法示例
pmad=4
pmnd
(广告连播时长下限)
说明
“广告连播时长下限”参数 (pmnd
) 和“广告连播时长上限”参数 (pmxd
) 接受变量值,结合使用此类参数可指定广告连播的时长范围(以毫秒为单位)。
这些参数用于在优化型广告连播中请求多个广告,此功能适用于使用高级视频产品包的发布商。使用广告规则时,Google Ad Manager 会自动添加此类信息。
不应将此参数用于 VMAP(当 ad_rule=1
时)。
用法示例
pmnd=0&pmxd=60000
pmxd
(广告连播时长上限)
说明
“广告连播时长下限”参数 (pmnd
) 和“广告连播时长上限”参数 (pmxd
) 接受变量值,结合使用此类参数可指定广告连播的时长范围(以毫秒为单位)。
这些参数用于在优化型广告连播中请求多个广告,此功能适用于使用高级视频产品包的发布商。使用广告规则时,Google Ad Manager 会自动添加此类信息。
不应将此参数用于 VMAP(当 ad_rule=1
时)。
用法示例
pmnd=0&pmxd=60000
pmxfwt
(广告连播强制观看时长上限)
说明
“广告连播强制观看时长上限”参数 (pmxfwt
) 接受变量值,以用于指定广告连播不可跳过式时长上限(以毫秒为单位)。
如果您支持广告连播同时包含不可跳过式视频广告和可跳过式视频广告,并且希望限制用户观看的广告时长,请使用此参数来指定用户需要观看的不可跳过式广告时长上限。
注意:在指定广告连播总时长上限(包括可跳过式广告的完整时长)时,“广告连播时长上限”参数 (pmxd
) 会取代此参数。
用法示例
pmxfwt=30000
pod
(广告连播编号)
pp
(广告素材配置文件)
说明
“广告素材配置文件”参数 (pp
) 接受变量值,用于控制哪些广告素材能够根据视频和音频广告素材配置文件中设定的配置进行投放。
用法示例
pp=creative_profile
要求和建议
虽然向任何特定实现投放广告时不需要此参数,但若要限制 Google Ad Manager 托管的广告素材(视频广告素材配置文件和音频广告素材配置文件)的媒体文件,则必须使用此参数。对于重定向或程序化广告,此属性用于确保该要求可用,但不会将媒体文件限制为仅限广告素材资料中选择的媒体文件。
ppt
(发布商隐私保护处理措施)
说明
“发布商隐私保护处理措施”参数 (ppt
) 接受常量值,用于指明是否针对广告请求关闭广告个性化功能。
此参数提供了一种强制投放非个性化广告的方法,该方法可能与 npa=1
和 rdp=1
不同。它会同时影响预订型交易和程序化需求。
详细了解发布商隐私保护处理措施。
用法示例
关闭广告个性化功能:
ppt=1
ppid
(发布商提供的标识符)
说明
“发布商提供的标识符”(PPID
) 参数接受对此标识符使用变量值,以便跨设备实现频次上限、受众群细分、定位、依序广告轮播以及基于受众群体的其他广告投放控制功能。
详细了解发布商提供的标识符。
用法示例
ppid=12JD92JD8078S8J29SDOAKC0EF230337
要求和建议
虽然向任何特定实现或交易类型投放广告时不需要此参数,但必须使用不依赖于平台的一致标识符。在没有其他标识符且可以提供给买方的情况下,可以使用此标识符。
ppos
(在广告连播中的位置)
说明
“在广告连播中的位置”参数 (ppos
) 接受变量值,用于表示在广告连播中的位置(例如,位置 1、位置 2 等)。
此参数仅适用于标准广告连播,随播广告自动填充功能需要使用此参数。 使用广告规则时,Google Ad Manager 会自动添加此类信息。
用法示例
ppos=2
ppsj
(发布商提供的信号 JSON)
说明
发布商提供的信号 JSON 参数 (ppsj
) 接受变量值,该值是一个采用 base64 编码的 JSON 对象,其中包含发布商提供的受众群体和情境数据,以提高程序化变现能力。
此参数可用于向买方/出价方发送特定信号。
用法示例
JSON object:
{
"PublisherProvidedTaxonomySignals": [{
"taxonomy": "IAB_AUDIENCE_1_1",
"values": ["6", "284"]
}]
}
应用 Base64 编码值:
eyJQdWJsaXNoZXJQcm92aWRlZFRheG9ub215U2l
nbmFscyI6W3sidGF4b25vbXkiOiJJQUJfQVVESUVOQ0V
fMV8xIiwidmFsdWVzIjpbIjEiLCIyODQiXX1dfQ
如需详细了解有效的 JSON 键值对,请参阅
HTML5 IMA SDK 示例。
ptpl
(广告插播模板 ID)
说明
“广告插播模板 ID”参数 (ptpl
) 和“名称”参数 (ptpln
) 接受变量值,用于指明应将哪个广告插播模板应用于优化型广告连播请求。
借助广告插播模板,您可配置广告插播时间点处应包含哪些广告插播位或自定义广告插播位,以及这些插播位应按什么顺序投放。
请求广告插播时间点模板时,只需提供其中一个参数即可。
用法示例
详细了解如何设置和请求广告插播时间点模板。
要求和建议
只有在直接请求广告插播时间点模板时,才需要使用这些参数。
ptpln
(广告插播模板名称)
说明
“广告插播模板 ID”参数 (ptpl
) 和“名称”参数 (ptpln
) 接受变量值,用于指明应将哪个广告插播模板应用于优化型广告连播请求。
借助广告插播模板,您可配置广告插播时间点处应包含哪些广告插播位或自定义广告插播位,以及这些插播位应按什么顺序投放。
请求广告插播时间点模板时,只需提供其中一个参数即可。
用法示例
详细了解如何设置和请求广告插播时间点模板。
要求和建议
只有在直接请求广告插播时间点模板时,才需要使用这些参数。
pubf
(Ad Exchange 代码中的公开底价)
说明
Ad Exchange 参数的公开底价 (pubf
) 和 Ad Exchange 参数的私下底价 (pvtf
) 接受变量值,这些值用于向 Ad Exchange 代码添加底价。
这些参数相当于 google_ad_public_floor
和 google_ad_private_floor
。
用法示例
公开底价:
pubf=123
私下发售:
pvtf=123
pvid
(应用组 ID)
说明
应用组 ID 参数 (pvid
) 接受变量值,此值设为 Android 应用组 ID;应用组范围参数 (pvid_s
) 接受常量值,此值表示应用组 ID 的范围(可以是 scope_app
或 scope_developer
)。
用法示例
pvid=[AppSetID_value]
pvid_s=scope_app
要求和建议
虽然向任何特定实现投放广告不需要此参数,但建议在 Android 设备的移动应用中进行程序化变现时使用此参数。
SDK 使用情况
当 IMA/PAL SDK 自动传递此字段时,采用非 SDK 实现方案的发布商必须调用应用组 SDK,并在广告请求中手动传递这些参数。
pvid_s
(应用组级范围)
说明
应用组 ID 参数 (pvid
) 接受变量值,此值设为 Android 应用组 ID;应用组范围参数 (pvid_s
) 接受常量值,此值表示应用组 ID 的范围(可以是 scope_app
或 scope_developer
)。
用法示例
pvid=[AppSetID_value]
pvid_s=scope_app
要求和建议
虽然向任何特定实现投放广告不需要此参数,但建议在 Android 设备的移动应用中进行程序化变现时使用此参数。
SDK 使用情况
当 IMA/PAL SDK 自动传递此字段时,采用非 SDK 实现方案的发布商必须调用应用组 SDK,并在广告请求中手动传递这些参数。
pvtf
(Ad Exchange 代码中的不公开底价)
说明
Ad Exchange 参数的公开底价 (pubf
) 和 Ad Exchange 参数的私下底价 (pvtf
) 接受变量值,这些值用于向 Ad Exchange 代码添加底价。
这些参数相当于 google_ad_public_floor
和 google_ad_private_floor
。
用法示例
公开底价:
pubf=123
私下发售:
pvtf=123
rdp
(限制数据处理)
说明
“受限的数据处理”参数 (rdp
) 接受常量值,用于指明广告请求应限制数据处理。
您可以通过启用限制数据处理广告资源网设置,在广告资源网一级限制数据处理。
用法示例
限制数据处理:
rdp=1
或 rdp
(不设置任何值)
不限制数据处理:
rdp=0
schain
(供应链)
说明
“供应链”(schain
) 参数接受一个变量值,该值应为序列化的 SupplyChain 对象。包含此参数时,Google 会在将任何收到的 schain
对象发送给买方之前,向其附加一个节点。
如需了解如何通过代码(而非 OpenRTB)传达 SupplyChain 信息,请参阅完整的 IAB 文档。
查看正确解析schain
需遵循的要求
下面根据 IAB 文档定义了 SupplyChain
对象的序列化:
{SupplyChainObject}!{SupplyChainNode array}。SupplyChainObject
和SupplyChainNode
属性都以英文逗号分隔,因此可选字段可以省略,并且可以选择性地排除相应的英文逗号分隔符。- 各个
SupplyChainNode
元素间用“!
”分隔。 - 如果任何属性的值包含需要进行网址编码的字符(例如“
,
”或“!
”),则应先对该值进行网址编码,然后再进行序列化。
序列化顺序
SupplyChainObject
属性按以下顺序进行序列化:
ver,complete
SupplyChainNode
属性按以下顺序进行序列化:
asi,sid,hp,rid,name,domain,ext
ext
的内容因广告交易平台而异。Google Ad Manager 不会解析此属性。有关如何序列化 SupplyChain 对象的示例
下面是序列化上述 SupplyChain
对象的两种方法示例:
1.0,1!exchange1,12345,1,bid-request-1,publisher1,publisher1.com!google.com,pub-12345678910,1,,,,
1.0,1!exchange1,12345,1,bid-request-1,publisher1,publisher1.com!google.com,pub-12345678910,1
用法示例
schain=1.0,1!exchange1,12345,1,bid-request-1,publisher1,publisher1.com!google.com,pub-12345678910,1,,,,
如果 asi
的值为 exchange,1
,则使用转义字符进行序列化后的结果如下所示:
1.0,1!exchange%2C1,12345,1,bid-request-1,publisher1,publisher1.com!google.com,pub-12345678910,1
要求和建议
虽然对于任何特定实现或交易类型而言,无需此参数即可投放广告,但对于在向 Google Ad Manager 发出请求之前利用支付中间方的发布商,此参数为必需参数。其中包括使用第三方广告服务器技术的发布商。
scor
(视频流 Correlator)
说明
“视频流 Correlator”(scor
) 参数接受变量值,此值应该是针对每个视频流生成的整数。
score
和 correlator
参数不必具有相同的整数值。不过,它们应在每次视频流播放期间保留各自的值,以便标识唯一的观看会话。
用法示例
scor=17
sdk_apis
(SDK API 框架)
说明
SDK API 框架 (sdk_apis
) 参数接受由以英文逗号分隔的常量整数值构成的列表,这些整数值表示播放器支持的所有 API 框架。
要求和建议
SDK 使用情况
使用 Programmatic Access Library (PAL) 的发布商会使用此参数。如果您在使用 IMA SDK 时尝试为此参数设置值,这些值将被 IMA SDK 支持的值替换。
sdmax
(可跳过式广告时长上限)
说明
“可跳过式广告时长上限”(sdmax
) 参数接受变量值,可让发布商为可跳过式广告指定所需的时长上限。
它是一个时长(以毫秒为单位),表示针对该特定广告请求,允许的可跳过式视频/音频广告素材时长上限。
您可以单独为可跳过式广告使用 sdmax
,也可以将其与现有的 max_ad_duration
参数结合使用,为可跳过式广告和不可跳过式广告提供不同的时长上限。
用法示例
将以下设置:
max_ad_duration
= 15000(15 秒)sdmax
= 45000(45 秒)
用于以下广告素材:
- 广告素材 A:不可跳过;30 秒
- 广告素材 B:可跳过;30 秒
会得到如下结果:
- 广告素材 A 将被滤除,因为它是不可跳过式广告,并且其时长超过了(不可跳过式广告)时长上限。
- 广告素材 B 将不会被滤除,因为虽然其时长超过了
max_ad_duration
,但它是可跳过式广告,并且其时长未超过可跳过式广告时长上限。
ssss
(服务器端拼接来源)
说明
服务器端拼接来源 (ssss
) 参数接受一个常量值,该值应设为 Google 为您的视频拼接技术供应商提供的一个认可的值。
如果视频拼接技术供应商使用 Google 的服务器到服务器集成服务,Google 会向供应商提供此值,然后供应商便能向您提供此值。如果对用来设置此参数的值有任何疑问,您可与 Google 客户经理联系。
用法示例
ssss=mystitcher
要求和建议
虽然对于任何特定实现或交易类型而言,无需此参数即可投放广告,但要使用服务器端实现,必须提供此参数。
tfcd
(“面向儿童”标记)
trt
(流量类型)
说明
流量类型 (trt
) 参数接受常量值,用于请求所购流量或自然流量。
用法示例
针对所购流量的请求:
trt=1
针对自然流量的请求:
trt=2
要求和建议
SDK 使用情况
如果请求中缺少流量类型参数,IMA SDK 不会填充默认值。在这类情况下,服务器会提供默认值 0
(未定义的流量)。
us_privacy
(IAB US Privacy)
说明
IAB 已弃用us_national
字符串,改为使用 GPP。不过,为了实现向后兼容性,Ad Manager 会继续读取并遵循传递的字符串。建议发布商查看 GPP 或其他隐私控制设置并迁离 us_national
。
vad_type
(视频广告类型)
说明
“视频广告类型”(vad_type
) 参数接受常量值,用于指明应返回线性广告还是非线性广告。
用法示例
返回线性广告:
vad_type=linear
返回非线性广告:
vad_type=nonlinear
vid
(视频 ID)
说明
内容来源 ID 参数 (cmsid
) 和视频 ID 参数 (vid
) 接受变量值。
要将广告定位到视频内容,主视频广告代码必须同时包含这两个参数。
cmsid
是每个内容来源的唯一编号。若要在 Google Ad Manager 中找到它,请依次点击视频、内容来源,然后点击相应来源的名称。vid
是用于标识特定视频的字符串或编号。此 ID 由托管内容的 CMS 分配。若要在 Google Ad Manager 中找到它,请依次点击视频、内容,然后点击特定视频内容。
用法示例
cmsid=[value]&vid=[value]
如果您要为包含视频点播内容的动态广告插播构建代码,则应使用可动态插入正确内容来源和视频 ID 的宏。
例如:cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%
要求和建议
虽然这些参数不是投放任何特定实现或交易类型的广告所必需的,但必须使用视频内容定位。
vpi
(内嵌视频播放列表)