借助 Dynamic Ad Insert API,您可以请求和跟踪 DAI 线性(直播)视频流。
服务:dai.google.com
以下所有 URI 都是 https://dai.google.com
的相对路径
方法:stream
方法 | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
为指定的事件 ID 创建 DAI 视频流。 |
HTTP 请求
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream
请求标头
参数 | |
---|---|
api‑key |
string 创建视频流时提供的 API 密钥必须对发布商的广告联盟有效。 API 密钥可以按照以下格式在 HTTP Authorization 标头中传递,而不是在请求正文中提供: Authorization: DCLKDAI key="<api-key>" |
路径参数
参数 | |
---|---|
assetKey |
string 数据流的事件 ID。 |
请求正文
请求正文的类型为 application/x-www-form-urlencoded
并包含以下参数:
参数 | ||
---|---|---|
dai-ssb |
可选 | 设置为 |
DFP 定位参数 | 可选 | 其他定位参数。 |
替换数据流参数 | 可选 | 替换数据流创建参数的默认值。 |
HMAC 身份验证 | 可选 | 使用基于 HMAC 的令牌进行身份验证。 |
响应正文
如果成功,响应正文将包含一个新的 Stream
。对于服务器端信标流,此 Stream
仅包含 stream_id
和 stream_manifest
字段。
开放式衡量
DAI API 的 Verifications
字段中包含用于进行 Open Measurement 验证的信息。此字段包含一个或多个 Verification
元素,其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。仅支持 JavaScriptResource
。如需了解详情,请参阅 IAB Tech Lab 和 VAST 4.1 规范。
方法:媒体验证
在播放期间遇到广告媒体标识符后,立即使用从上文的 stream 端点获取的 media_verification_url 发出请求。服务器端信标流(服务器会启动媒体验证)不需要这些请求。
对 media verification
端点的请求具有幂等性。
方法 | |
---|---|
media verification |
GET /{media_verification_url}/{ad_media_id}
向 API 发出媒体验证事件的通知。 |
HTTP 请求
GET https://{media-verification-url}/{ad-media-id}
响应正文
media verification
会返回以下响应:
- 如果媒体验证成功且所有 ping 均已发送,则为
HTTP/1.1 204 No Content
。 - 如果请求因网址格式不正确或过期而无法验证媒体,则为
HTTP/1.1 404 Not Found
。 - 如果之前针对此 ID 的验证请求已成功完成,则返回
HTTP/1.1 404 Not Found
。 - 如果此时已有其他请求在发送 ping,则为
HTTP/1.1 409 Conflict
。
广告媒体 ID (HLS)
系统将使用为“用户定义的文本信息”帧预留的 TXXX
键,在 HLS 定时元数据中对广告媒体标识符进行编码。帧的内容不会加密,并且始终以文本 "google_"
开头。
在发出每个广告验证请求之前,应将框架的全部文字内容附加到广告验证网址。
方法:metadata
位于 metadata_url
的元数据端点会返回用于构建广告界面的信息。元数据端点不适用于服务器端信标流(其中服务器负责启动广告媒体验证)。
方法 | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
检索广告元数据信息。 |
HTTP 请求
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
响应正文
如果成功,响应将返回一个 PodMetadata
实例。
使用元数据
元数据有三个独立的部分:tags
、ads
和广告 breaks
。数据的入口点是 tags
部分。然后,遍历代码并找到第一个条目,该条目的名称是视频流中广告媒体 ID 的前缀。例如,您的广告媒体 ID 可能如下所示:
google_1234567890
然后,找到一个名为 google_12345
的代码对象。在这种情况下,它与广告媒体 ID 匹配。找到正确的广告媒体前缀对象后,您可以查找广告 ID、广告插播时间点 ID 和事件类型。然后,广告 ID 用于将 ads
对象编入索引,广告插播时间点 ID 用于 breaks
对象。
响应数据
数据流
数据流用于以 JSON 格式渲染新创建的数据流的资源列表。JSON 表示法 |
---|
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
字段 | |
---|---|
stream_id |
string GAM 数据流标识符。 |
stream_manifest |
string 数据流的清单网址,用于检索 HLS 中的多变体播放列表或 DASH 中的 MPD。 |
hls_master_playlist |
string (已弃用)HLS 多变体播放列表网址。请改用“stream_manifest”。 |
media_verification_url |
string 用作跟踪播放事件的基础端点的媒体验证网址。 |
metadata_url |
string 用于轮询与即将进行的直播广告活动的定期信息有关的元数据网址。 |
session_update_url |
string 用于更新此视频流的定位参数的会话更新网址。 系统会在初始视频流创建请求期间捕获定位参数的原始值。 |
polling_frequency |
number 从 或 heartbeat_url 请求 metadata_url 时的轮询频率(以秒为单位)。 |
PodMetadata
PodMetadata 包含有关广告、广告插播时间点和媒体 ID 代码的元数据信息。JSON 表示法 |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
字段 | |
---|---|
tags |
map[string, object(TagSegment)] 按标记前缀编入索引的代码段地图。 |
ads |
map[string, object(Ad)] 按广告 ID 编入索引的广告地图。 |
ad_breaks |
map[string, object(AdBreak)] 按广告插播时间点 ID 编入索引的广告插播时间点地图。 |
TagSegment
TagSegment 包含对广告、广告插入点和事件类型的引用。不应对 type="progress" 的 TagSegment 执行 ping 操作到广告媒体验证端点。JSON 表示法 |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
字段 | |
---|---|
ad |
string 此代码的广告的 ID。 |
ad_break_id |
string 此代码的广告插播时间点的 ID。 |
type |
string 此代码的事件类型。 |
AdBreak
AdBreak 描述视频流中的单个广告插播时间点。它包含时长、类型(中间/前/后)和广告数量。JSON 表示法 |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
字段 | |
---|---|
type |
string 有效的广告插播类型包括:前、中和后。 |
duration |
number 此广告插播时间点的广告总时长(以秒为单位)。 |
expected_duration |
number 广告插播时间点的预计时长(以秒为单位),包括所有广告和所有可选广告。 |
ads |
number 广告插播时间点中的广告数量。 |
广告
广告描述视频流中的广告。JSON 表示法 |
---|
{ "ad_break_id": string, "position": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
字段 | |
---|---|
ad_break_id |
string 此广告的广告插播时间点的 ID。 |
position |
number 此广告在广告插播时间点中的位置(从 1 开始)。 |
duration |
number 广告时长(以秒为单位)。 |
title |
string 广告的可选标题。 |
description |
string 广告的可选广告内容描述。 |
advertiser |
string 可选的广告客户标识符。 |
ad_system |
string 可选广告系统。 |
ad_id |
string 可选广告 ID。 |
creative_id |
string 可选的广告素材 ID。 |
creative_ad_id |
string 可选的广告素材广告 ID。 |
deal_id |
string 可选交易 ID。 |
clickthrough_url |
string 可选的点击后到达网址。 |
click_tracking_urls |
string 可选的点击跟踪网址。 |
verifications |
[object(Verification)] 可选的 Open Measurement 验证条目,其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。 |
slate |
boolean 可选布尔值,表示当前条目是可选广告。 |
icons |
[object(Icon)] 图标列表,为空时应将其省略。 |
wrappers |
[object(Wrapper)] 封装容器列表,为空时应将其省略。 |
universal_ad_id |
object(UniversalAdID) 可选的通用广告 ID。 |
extensions |
string VAST 中所有 <Extension> 节点的可选列表。 |
companions |
[object(Companion)] 可与此广告一起展示的可选随播广告。 |
interactive_file |
object(InteractiveFile) 应在广告播放期间展示的可选互动广告素材 (SIMID)。 |
Icon
图标包含有关 VAST 图标的信息。JSON 表示法 |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
字段 | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
ClickData 包含有关图标点击的信息。JSON 表示法 |
---|
{ "url": string, } |
字段 | |
---|---|
url |
string |
FallbackImage
FallbackImage 包含 VAST 后备图片的相关信息。JSON 表示法 |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
字段 | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
Wrapper
封装容器包含有关封装容器广告的信息。如果交易 ID 不存在,则不会显示。JSON 表示法 |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
字段 | |
---|---|
system |
string 广告系统标识符。 |
ad_id |
string 用于封装容器广告的广告 ID。 |
creative_id |
string 封装容器广告所用的广告素材 ID。 |
creative_ad_id |
string 用于封装容器广告的广告素材 ID。 |
deal_id |
string 封装容器广告的可选交易 ID。 |
验证
Verification 包含 Open Measurement 相关信息,这些信息有助于第三方可见度和验证衡量。目前仅支持 JavaScript 资源。请访问 https://iabtechlab.com/standards/open-measurement-sdk/JSON 表示法 |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
字段 | |
---|---|
vendor |
string 验证供应商。 |
java_script_resources |
[object(JavaScriptResource)] 用于验证的 JavaScript 资源列表。 |
tracking_events |
[object(TrackingEvent)] 用于验证的跟踪事件列表。 |
parameters |
string 传递给引导加载程序验证码的不透明字符串。 |
JavaScriptResource
JavaScriptResource 包含用于通过 JavaScript 进行验证的信息。JSON 表示法 |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
字段 | |
---|---|
script_url |
string JavaScript 载荷的 URI。 |
api_framework |
string APIFramework 是执行验证码的视频框架的名称。 |
browser_optional |
boolean 此脚本是否可以在浏览器外部运行。 |
TrackingEvent
TrackingEvent 包含客户端在特定情况下应对其执行 ping 操作的网址。JSON 表示法 |
---|
{ "event": string, "uri": string, } |
字段 | |
---|---|
event |
string 跟踪事件类型。 |
uri |
string 要执行 ping 操作的跟踪事件。 |
UniversalAdID
UniversalAdID 用于提供在不同广告系统中维护的唯一广告素材标识符。JSON 表示法 |
---|
{ "id_value": string, "id_registry": string, } |
字段 | |
---|---|
id_value |
string 广告所选广告素材的通用广告 ID。 |
id_registry |
string 一个字符串,用于标识收录所选广告素材的通用广告 ID 的注册网站的网址。 |
随播广告
随播广告包含可与广告一起展示的随播广告的相关信息。JSON 表示法 |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
字段 | |
---|---|
click_data |
object(ClickData) 此随播广告素材的点击数据。 |
creative_type |
string VAST 中 <StaticResource> 节点上的 CreativeType 属性(如果它是静态类型的随播广告素材)。 |
height |
int32 此随播广告素材的高度(以像素为单位)。 |
width |
int32 此随播广告素材的宽度(以像素为单位)。 |
resource |
string 对于静态和 iframe 随播广告,这将成为要加载和显示的网址。对于 HTML 随播广告,这应是应作为随播广告显示的 HTML 代码段。 |
type |
string 此随播广告素材的类型。可以是静态、iframe 或 HTML。 |
ad_slot_id |
string 此随播广告素材的广告位 ID。 |
api_framework |
string 此配套应用的 API 框架。 |
tracking_events |
[object(TrackingEvent)] 此随播广告素材的跟踪事件列表。 |
InteractiveFile
InteractiveFile 包含应在广告播放期间展示的互动式广告素材(即 SIMID)的相关信息。JSON 表示法 |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
字段 | |
---|---|
resource |
string 互动式广告素材的网址。 |
type |
string 作为资源提供的文件的 MIME 类型。 |
variable_duration |
boolean 此广告素材是否会请求延长时长。 |
ad_parameters |
string VAST 中 <AdParameters> 节点的值。 |