借助 Dynamic Ad Placement 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 密钥必须对发布商的广告资源网有效。 您可以在 HTTP Authorization 标头中通过以下格式传递 API 密钥,而不是在请求正文中提供该密钥: 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 数据流标识符。 |
stream_manifest |
string 流的清单,对应于 HLS 中的主播放列表或 DASH 中的 MPD。创建服务器端信标流时,这是响应中除“stream_id”之外的唯一字段。 |
hls_master_playlist |
string (已弃用)HLS 主播放列表网址。请改用“stream_manifest”。 |
media_verification_url |
string 媒体验证网址。 |
metadata_url |
string 广告媒体元数据网址。 |
session_update_url |
string 会话更新网址。 |
polling_frequency |
number 建议的元数据网址轮询频率(以秒为单位)。 |
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 有效的插播时间点类型包括:pre、mid 和 post。 |
duration |
number 此广告插播时间点的广告总时长(以秒为单位)。 |
expected_duration |
number 广告插播时间点的预期时长(以秒为单位),包括所有广告和所有可选广告。 |
ads |
number 广告插播时间点的广告数量。 |
Ad
广告用于描述视频流中的广告。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 跟踪事件类型,目前唯一的选项是 VAST 4.1 规范中指定的“verificationNotExecuted”。 |
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, } |
字段 | |
---|---|
click_data |
object(ClickData) 此随播广告素材的点击数据。 |
creative_type |
string 如果是静态类型的随播广告,则 VAST 中 <StaticResource> 节点上的 CreativeType 属性。 |
height |
int32 此随播广告素材的高度(以像素为单位)。 |
width |
int32 此随播广告的宽度(以像素为单位)。 |
resource |
string 对于静态随播广告素材和 iframe 随播广告素材,这是指要加载和显示的网址。对于 HTML 随播广告,这将是应作为随播广告显示的 HTML 代码段。 |
type |
string 此随播广告素材的类型。它可以是静态、iframe 或 HTML。 |
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> 节点的值。 |