VAST 广告代码网址参数

VAST 广告代码会被播放器用来检索视频广告和音频广告。如需使用正确的参数组建 VAST 广告代码网址,请参阅下面的表格。一旦组建好该网址,您便可使用 VAST 套件检查器测试该网址。

VAST 广告代码既支持 https 网址也支持 http 网址。展示跟踪网址和 VAST 跟踪网址遵循 SSL 设置,并会酌情返回 https 或 http。由于点击后到达网址和点击跟踪网址是从另一网页重定向的,因此它们是 http 网址。

为了确保能够处理所有广告插播时间点同时有广告投放时产生的繁重流量,直播视频广告代码网址的路径中必须包含 /live

如果您想投放音频广告,相应的广告代码网址必须包含设为 audioaudio_videoad_type 参数。

示例

下面是一个包含参数和指定值的 VAST 广告代码网址示例:

https://securepubads.g.doubleclick.net/gampad/ads?env=vp&gdfp_req=1&output=vast&iu=/1234/video-demo&sz=400x300&unviewed_position_start=1&ciu_szs=728x90,300x250

您也可参考这些代码示例来检查和测试代码。

详细了解参数类型和要求

值为常量的必需参数

所有 VAST 广告代码网址都需要使用以下参数,其中每一个参数的值均为常量。例如,若 env 参数设为 vp,则表示请求是来自视频播放器。

env
gdfp_req
unviewed_position_start

值为变量的必需参数

所有 VAST 广告代码网址都需要使用以下参数,这些参数的值均为变量。请参阅说明和示例值来了解它们的使用方法。

correlator
description_url
iu
output
sz
url

可选参数

下面介绍的是可选参数。这些参数的值均为变量。请参阅说明和示例值来了解它们的使用方法。

aconp
ad_rule
ciu_szs
cmsid | vid
cust_params
hl
msid | an
nofb
pp
ppid
rdid | idtype | is_lat
rdp
tfcd
npa
vconp
vpa
vpi
vpmute

自定义 SDK 参数

以下是 Google IMA SDK 设置的默认参数。如果您未使用 IMA SDK,请在 VAST 广告代码网址中仅添加以下参数。

当前的 Ad Manager 架构要求视频广告请求包含先前在视频流和网页上展示的广告的相关信息。该信息有助于您大致了解过去发生的活动以及计算已排除和重复的广告个数。

afvsz
excl_cat
lip
max_ad_duration | min_ad_duration
mridx
pmad
pmnd | pmxd
pod
ppos
sid
scor
vad_type
vpos
wta
参数说明要求
env

(环境)

表示这是一项插播广告请求或者该请求是明确来自视频播放器。

可取值包括 instream(可用于视频和音频广告)或 vp(仅可用于视频广告)。


例如:

视频和/或音频:
env=instream

仅限视频:
env=vp

必需

gdfp_req

(Ad Manager 架构指示器)

表示用户在 Ad Manager 架构中。


例如:

gdfp_req=1

必需

unviewed_position_start

(延迟记录展示次数)

将此值设置为“1”可对视频启用延迟记录展示次数。


例如:

unviewed_position_start=1

必需

output

(广告输出格式)

广告的输出格式。

请根据您为广告联盟启用的 VAST 版本(例如 VAST 4)来使用 output=vast。对于您网站中的特定广告代码或特定部分,您可以通过 output=xml_vast3 明确要求使用 VAST 3,或通过 output=xml_vmap1 明确要求使用 VMAP 1。

请注意,对于 VAST,如果您的视频播放器使用 IMA SDK,则视频广告请求的输出参数将始终设为 output=xml_vast4。这不会导致可靠性方面的风险,因为此 SDK 可向后兼容任何第三方广告服务器可能投放的所有 VAST 版本。

若要返回您为广告联盟启用的默认 VMAP 版本(如 VMAP 1),请使用 output=vmap。如果您要在 VMAP 内部返回 VAST,则可以使用 xml_vmap1_vast3xml_vmap1_vast4 指定要返回的 VAST 版本。


例如:

vast(适用于您广告联盟的默认 VAST 设置)
xml_vast3(适用于 VAST 3)
xml_vast4(适用于 VAST 4)

vmap(适用于您广告联盟的默认 VMAP 设置)
output=xml_vmap1(适用于 VMAP1)
xml_vmap1_vast3(适用于 VMAP1,且会返回 VAST3)
xml_vmap1_vast4(适用于 VMAP1,且会返回 VAST4)

必需

iu

(广告单元)

当前的广告单元。

采用以下格式:
/network_id/.../ad_unit


例如:

iu=/6062/videodemo

必需

sz

(尺寸)

主视频广告位的尺寸。多个尺寸应以竖线 (|) 字符进行分隔。

请勿在尺寸后面添加“v”。


例如:

sz=400x300

必填
(仅请求“ad_type=audio”时为可选)

description_url

(说明网址)

此值应该是能说明在网页上播放的视频的网址。它通常是视频播放器所在的网页,但也可以是包含视频介绍文字的网页。*

如果是网页视频播放器,您必须始终对 description_url 进行网址编码。

如果是移动应用内视频播放器,您则应发送未经网址编码的 description_url 值。

如果您使用 Ad Exchange,则必须填写该字段。了解详情

*此参数不是由适用于 CTV 的 IMA SDK 自动设置的,需要手动设置。


例如:

经过网址编码:
description_url=https%3A%2F%2Fwww.sample.com%2Fgolf.html

未经网址编码:
description_url=https://www.sample.com/golf.html

必需

url

(网址)

这是发送广告请求的完整网址。在网页中,它是显示视频播放器的网页的网址。在应用中,它表示文件包名称。

如果您使用 IMA SDK,则它会自动设置网址值。如果您的播放器设置了此值,IMA SDK 会将其替换成自己的值。


例如:

url=https://www.videoad.com/golf.html

必需

correlator

(Correlator)

源于同一次网页浏览的多项请求会使用的同一个随机正数值。

在进行竞争排除(包括在没有 Cookie 的环境中)时会用到 Correlator。

如果您使用 IMA SDK,则会自动设置 Correlator 值。如果您的播放器尝试设置此值,则 IMA SDK 会将其替换成自己的随机值。

如果您未使用 IMA SDK,请确保将此值设置为没有被多次网页浏览重复使用的真正随机值。


例如:

correlator=4345645667

必需

aconp

(连续播放音频)

建议使用,请参阅 MRC 音频衡量指南

指明播放器是否会连续播放音频内容。

可取值包括 2(如果开启连续播放)和 1(如果关闭连续播放)。

如果此参数未知,则应使其保持未设置状态。


例如:

开启连续播放:
aconp=2

关闭连续播放:
aconp=1

可选

ad_rule

(广告规则)

指明是返回 VAST 广告素材还是广告规则响应。如果您使用的是广告规则,则应使用 ad_rule=1。其他请求应使用 ad_rule=0(或直接排除此参数)。

详细了解广告规则


例如:

ad_rule=0 表示请求广告素材 (VAST)

ad_rule=1 表示请求广告规则 (VMAP)

可选

ad_type

(广告类型)

指明应针对该请求返回哪类广告。*

可取值包括 audio(仅返回音频广告)、video(仅返回视频广告)或 audio_video(返回音频广告或视频广告)。

*目前,若要仅返回视频广告,可以不传递此参数。


例如:

返回音频广告:
ad_type=audio

返回音频广告或视频广告:
ad_type=audio_video

若要返回音频广告,必须传递此参数

ciu_szs

(随播广告尺寸)

随播广告尺寸列表(以英文逗号分隔)。

竖线分隔 (|) 值表示多尺寸广告位。


例如:

ciu_szs=728x90,300x250

多尺寸广告位的尺寸:
ciu_szs=728x90,300x200|300x250

可选

cmsid
vid

(内容来源 ID、视频 ID)

将广告定位到视频内容,主视频广告代码必须同时包含 cmsidvid

cmsid 是每个内容来源的唯一编号。要在 Ad Manager 中找到它,请依次点击视频 接着点击 内容来源,然后点击相应内容来源的名称。

vid 是用于标识特定视频内容片段的字符串或编号。此 ID 由托管内容的 CMS 分配。要在 Ad Manager 中找到它,请依次点击视频 接着点击 内容,然后点击列表中的相应内容。


例如:

cmsid=[value]&vid=[value]

如果您要为包含视频点播内容的动态广告插播构建代码,则应使用可动态插入正确 cmsidvid

例如:

cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%

可选

cust_params

(自定义键值对参数)

查看添加键值对的方法示例。

可选

hl

(语言)

语言代码,用于请求使用相应语言的广告。

在对 Ad Exchange 或 AdSense 视频广告中的视频进行动态分配的过程中,此参数用于指定在进行广告选择和视频广告呈现时所使用的语言。

语言代码可以是任意的 ISO 639-1(两个字母)或 ISO 639-2(三个字母)代码。请参阅有效代码列表。

如果省略,则默认为支持可在 Ad Exchange 中根据语言定位广告的任何语言。


例如:

hl=it

可选

msid
an

(应用 ID 和名称)

这两个参数应该应用于从移动应用和联网电视设备发送的所有请求。msid 参数是应用 ID,应在不使用 IMA SDK 时用于对 Google 的直接 VAST 调用。an 参数是应用名称。

大多数程序化视频广告都要求在移动应用或联网电视广告资源请求中同时使用这两个值。


例如:

msid=com.package.publisher an=sample%20app

可选

nofb

(后备广告已停用)

指明广告请求是否不应返回“视频后备广告”的播放列表。

详细了解视频后备广告


例如:

nofb=1

可选

pp

(视频和音频广告素材配置文件)

控制哪些广告素材能够根据视频和音频广告素材配置文件中设置的配置进行投放。

详细了解广告素材配置文件


例如:

pp=creative_profile

可选

ppid

(发布商提供的标识符)

通过发布商提供的标识符 (PPID),发布商可以发送标识符,以便跨设备实现频次上限、受众群细分和定位、依序广告轮播以及基于受众群体的其他广告投放控制功能。

了解详情


例如:

ppid=12JD92JD8078S8J29SDOAKC0EF230337

可选

rdid
idtype
is_lat

(可重置设备标识符)

对于原生应用(而非网站或移动网站),SDK 会通过以下各项的参数将用于用户定位的可重置设备标识符传递到视频流请求:rdididtypeis_lat。在 SSB 视频流中,您必须将这些标识符作为显式参数进行传递,就像处理客户端视频广告解决方案广告请求时一样。了解详情

几乎所有程序化视频广告都需要这些值。


查看可重置设备标识符的详细示例。

可选

rdp

(限制数据处理)

标记广告请求以
限制数据处理。

您必须明确设置 rdp=1 或仅添加 rdp(不设置任何值),才能限制数据处理。缺少此参数或设置了 rdp=0 的广告请求不会限制数据处理,除非启用了限制数据处理这项广告联盟设置。


例如:

rdp=1

可选

tfcd

(面向儿童的内容)

将广告请求标记为面向儿童的内容。

详细了解 tfcd


例如:

tfcd=1

可选

npa

(非个性化广告)

将广告请求标记为非个性化。

要将相应广告请求标记为非个性化,您必须明确设置 npa=1,或直接添加 npa(不设置任何值)。缺少此参数或设为 nap=0 的广告请求会默认为请求投放个性化广告。

详细了解广告个性化


例如:

npa=1

可选

vconp

(持续播放视频)

建议使用,请参阅 MRC 视频衡量指南

指明播放器是否会在一个内容视频播放完后继续播放另一个内容视频(类似于电视广播)。

可能的值包括 2(如果开启连续播放)和 1(如果关闭连续播放)。

如果此参数未知,则应使其保持未设置状态。


例如:

开启连续播放:
vconp=2

关闭连续播放:
vconp=1

可选

vpa

(视频自动播放)

建议使用,请参阅 MRC 视频衡量指南

指明广告是会自动播放还是需经点击才能开始播放。

可能的值包括:click(如果网页等待用户操作)或 auto(如果视频自动播放)。

如果此参数未知,则应使其保持未设置状态。


例如:

自动播放:
vpa=auto

点击播放:
vpa=click

可选

vpi

(视频播放列表 inred)

指明是否投放内嵌 VMAP(在 VMAP 内部返回 VAST)。

该参数可用于缩短延迟时间,并保证在整个视频流中实现频次上限和竞争性排除规则。

可取值包括 1(可返回 VAST)和 0(或未设置,可返回重定向代码)。


例如:

返回 VAST:
vpi=1

返回重定向代码:
vpi=0

可选

vpmute

(视频播放静音)

建议使用,请参阅 MRC 视频衡量指南

指明是否在视频播放器处于静音状态时开始播放广告。

可能的值的包括 1(设为静音)和 0(不设为静音)。

如果此参数未知,则应使其保持未设置状态。


例如:

设为静音:
vpmute=1

不设为静音:
vpmute=0

可选

afvsz

(非线性广告尺寸)

可在视频广告位中展示的非线性广告尺寸的列表(以英文逗号分隔)。

这些尺寸只能是下列任一受支持的尺寸:

  • 200x200
  • 250x250
  • 300x250
  • 336x280
  • 450x50
  • 468x60
  • 480x90
  • 729x90

当使用 IMA SDK 时,此字段中的值将改为介于 nonLinearAdSlotWidthnonLinearAdSlotHeight 之间所有受支持的尺寸。


例如:

支持所有尺寸:
afvsz=200x200,250x250,
300x250,336x280,
450x50,468x60,
480x90,728x90

最大宽度为 250:
afvsz=200x200,250x250

最大高度为 60:
afvsz=450x50,468x60

最大宽度为 100:
//empty; no values supported

如果非线性尺寸不受支持,则可以省略该参数或将其留空。

广告连播

(广告连播编号)

表示视频中的广告连播。对于第一次广告连播,传递的值为 pod=1,对于第二次广告连播,传递的值是 pod=2,依此类推。用于竞争排除、频次上限和相关功能。


例如:

pod=3

若想使竞争排除、频次上限和相关功能正常运行,必须传递此参数。

ppos

(在广告连播中的位置)

表示在广告连播中的位置。随播广告自动填充功能需要使用此参数。对于第一个位置,传递 &ppos=1;对于第二个位置,传递 &ppos=2,依此类推。用于竞争排除、频次上限和相关功能。

此参数仅适用于标准广告连播。


例如:

ppos=2

若想使竞争排除、频次上限和相关功能正常运行,必须传递此参数。

vpos

(前贴片广告位、插播广告位或后贴片广告位)

指明广告请求是从前贴片广告位、插播广告位还是后贴片广告位发出的。


例如:

vpos=preroll
vpos=midroll
vpos=postroll

可选

mridx

(插播广告位编号)

数字索引,用于指明哪个插播广告位发出了广告请求(第 1 个、第 2 个、第 3 个,依此类推)


例如:

mridx=2

可选

lip

(标准广告连播中的最后一个位置)

在广告连播中,如果广告请求是从最后一个位置发出的,则必须添加此参数。

此参数仅适用于标准广告连播。


例如:

lip=true

标准广告连播必需参数

min_ad_duration
max_ad_duration

(广告时长)

结合使用这两个参数可指定广告的时长范围(以毫秒为单位)。

用于请求单个广告。


例如:

min_ad_duration=15000&max_ad_duration=30000

可选

pmnd
pmxd

(广告连播时长)

结合使用这两个参数可指定广告连播的时长范围(以毫秒为单位)。

用于请求多个广告(即广告连播)。

这些参数专用于面向拥有高级视频产品包的发布商提供的优化型广告连播,不应该用于 VMAP(当 ad_rule=1 时)。


例如:

pmnd=0&pmxd=60000

优化型广告连播必需参数

pmad

(广告连播中的广告数量上限)

广告连播中的广告数量上限。

此参数专用于面向拥有高级视频产品包的发布商提供的优化型广告连播,不应该用于 VMAP(当 ad_rule=1 时)。


例如:

pmad=4

可选

excl_cat

(排除类别)

用于屏蔽包含相关排除标签的所有订单项,使其不符合给定广告请求的条件;与 cust_params 结合使用。


例如:

&custom_params=excl_cat
%3Dairline_excl_label%7C

可选

scor

(视频流专属编号)

针对每个视频流生成的整数;在同一个视频流中,此数值必须保持不变;在同一次网页浏览中,此数值必须是独一无二的。如果用户在同一网页上观看多个视频,则该参数可用于竞争排除、频次上限和相关功能。


例如:

scor=17

若想使竞争排除、频次上限和相关功能正常运行,必须传递此参数。

sid

(会话 ID)

一种旨在保证用户隐私安全的广告标识符,仅可用于实现频次上限。根据 IAB 的 IFA 指南,此参数应以 UUID 格式填充。了解详情


例如:

123e4567-e89b-12d3-a456-426614174000

当请求中不含 PPID 或其他用户 ID(在 CTV/OTT 上通常为 RDID)或者已为用户启用“限制广告跟踪”(LAT) (is_lat=1) 时,若想让竞争性排除规则、频次上限和相关功能在 CTV/OTT 平台上正常运行,必须传递此参数。

vad_type

(线性或非线性广告)

指明应针对广告请求返回线性广告还是非线性广告。


例如:

vad_type=linear
vad_type=nonlinear

可选

wta

(为什么显示该广告?)

指明视频播放器对呈现“为什么显示该广告?”的支持能力。

当使用 IMA SDK 时,系统会自动支持此操作。当未使用 IMA SDK 时,视频播放器必须实现 VAST IconIconClickFallbackImage 支持(如 IAB VAST 标准中所述)。

如果您使用 Ad Exchange,则必须填写此字段。了解详情

对于公开竞价和/或没有随播广告位的情况,音频广告请求应发送 wta=0。如果已提供随播广告位,并且所有设有受众群体定位的广告系列都提供了 WTA 披露信息,则 wta 参数可以省略或设为 1


例如:

支持:
1

不支持:
0

如果您使用 Ad Exchange,则必须准确设置此参数。