动态广告插播 VOD API

借助动态广告插播 API，您可以请求和跟踪 DAI 视频点播 (VOD) 视频流。支持 HLS 和 DASH 流。

服务：dai.google.com

stream 方法的路径相对于 https://dai.google.com

方法：stream

方法
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

为指定的内容来源和视频 ID 创建 HLS DAI 视频流。

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

为指定的内容来源和视频 ID 创建 DASH DAI 视频流。

HTTP 请求

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

请求标头

参数
api‑key string

创建直播时提供的 API 密钥必须对发布商的网络有效。

API 密钥可以采用以下格式在 HTTP Authorization 标头中传递，而不是在请求正文中提供：

Authorization: DCLKDAI key="<api-key>"

路径参数

参数
content-source string

相应直播的 CMS ID。

video-id string

相应直播的视频 ID。

请求正文

请求正文的类型为 application/x-www-form-urlencoded，包含以下参数：

参数
dai-ssb 可选

设置为 true 可创建服务器端信标流。 默认值为 false。默认流的跟踪由客户端发起，并在服务器端进行 ping 操作。
DFP 定位参数 可选 其他定位参数。
替换视频流参数 可选 替换视频流创建参数的默认值。
HMAC 身份验证 可选 使用基于 HMAC 的令牌进行身份验证。

响应正文

如果成功，响应正文将包含一个新的 Stream。对于服务器端信标传送流，此 Stream 仅包含 stream_id 和 stream_manifest 字段。

开放式衡量

Verifications 字段包含非服务器端信标流的 Open Measurement 验证信息。Verifications 包含一个或多个 Verification 元素，这些元素列出了您需要使用第三方衡量代码验证广告素材播放的资源和元数据。仅支持 JavaScriptResource。如需了解详情，请参阅 IAB Tech Lab 和 VAST 4.1 规范。

方法：媒体验证

在播放期间遇到广告媒体标识符后，立即使用 stream 端点中的 media_verification_url 发出请求。media_verification_url 是绝对路径。 对于服务器端信标流（由服务器发起媒体验证），无需发送媒体验证请求。

对 media verification 端点的请求是幂等的。

方法
media verification GET {media_verification_url}/{ad_media_id}

向 API 通知媒体验证事件。

HTTP 请求

GET {media-verification-url}/{ad-media-id}

响应正文

media verification 返回以下回答：

  • 如果媒体验证成功且所有 ping 都已发送，则为 HTTP/1.1 204 No Content。
  • 如果请求因网址格式不正确或过期而无法验证媒体，则为 HTTP/1.1 404 Not Found。
  • HTTP/1.1 404 Not Found 如果之前针对相应 ID 的验证请求成功完成。
  • 如果此时另一个请求已在发送 ping，则为 HTTP/1.1 409 Conflict。

广告媒体 ID (HLS)

广告媒体标识符将使用为“用户定义的文本信息”帧预留的键 TXXX 编码到 HLS 定时元数据中。帧的内容将处于未加密状态，并且始终以文本 "google_" 开头。

框架的整个文本内容应附加到每个广告验证请求的 media_verification_url 中。

广告媒体 ID (DASH)

广告媒体标识符将通过使用 DASH 的 EventStream 元素插入到清单中。

每个 EventStream 都将具有 urn:google:dai:2018 的方案 ID URI。 这些事件将包含 messageData 属性，该属性包含以 "google_" 开头的广告媒体 ID。messageData 属性的全部内容应附加到每个广告验证请求的 media_verification_url 中。

响应数据

数据流

流用于以 JSON 格式呈现新创建的流的所有资源的列表。
JSON 表示法
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
字段
stream_id string

数据流标识符。
total_duration number

直播时长（以秒为单位）。
content_duration number

不含广告的内容时长（以秒为单位）。
valid_for string

时长视频流的有效时长，采用“00h00m00s”格式。
valid_until string

以 RFC 3339 格式表示的直播有效截止日期。
subtitles [object(Subtitle)]

字幕列表。如果为空，则省略。仅限 HLS。
hls_master_playlist string

（已弃用）HLS 主播放列表网址。使用 stream_manifest。仅限 HLS。
stream_manifest string

直播的清单。对应于 HLS 中的主播放列表和 DASH 中的 MPD。 这是创建服务器端信标流时，响应中除“stream_id”之外的唯一字段。
media_verification_url string

媒体验证网址。
apple_tv object(AppleTV)

特定于 AppleTV 设备的可选信息。仅限 HLS。
ad_breaks [object(AdBreak)]

AdBreak 的列表。如果为空，则省略。

AppleTV

AppleTV 包含特定于 Apple TV 设备的信息。
JSON 表示法
{
  "interstitials_url": string,
}
字段
interstitials_url string

插页式广告网址。

AdBreak

AdBreak 用于描述视频流中的单个广告插播时间点。它包含位置、时长、类型（插播/前贴片/后贴片）和广告列表。
JSON 表示法
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
字段
type string

有效的插播类型包括：mid、pre 和 post。
start number

插播广告开始播放的时间（以秒为单位）。
duration number

广告插播时间点的时长（以秒为单位）。
ads [object(Ad)]

广告列表。如果为空，则省略。
广告：指信息流中的广告。它包含广告在插播中的位置、广告时长和一些可选的元数据。
JSON 表示法
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
字段
seq number

广告在插播时段中的位置。
start number

广告在视频流中的开始位置（以秒为单位）。
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

可选的点击后到达网址。
icons [object(Icon)]

图标列表，如果为空则省略。
wrappers [object(Wrapper)]

封装容器列表。如果为空，则省略。
events [object(Event)]

广告中的事件列表。
verifications [object(Verification)]

可选的开放式衡量验证条目，其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。
universal_ad_id object(UniversalAdID)

可选的通用广告 ID。
companions [object(Companion)]

可能会与此广告一起展示的可选随播广告。
interactive_file object(InteractiveFile)

应在广告播放期间展示的可选互动式广告素材 (SIMID)。
skip_metadata object(SkipMetadata)

可跳过式广告的可选元数据。如果设置了此属性，则表示相应广告可跳过，并包含有关如何处理跳过界面和跟踪事件的说明。
extensions string

VAST 中所有 <Extension> 节点的可选列表。

活动

事件包含事件类型和事件的呈现时间。
JSON 表示法
{
  "time": number,
  "type": string,
}
字段
time number

相应活动的展示时间。
type string

相应事件的类型。

副标题

副标题描述了视频串流的辅助信息文件字幕轨道。它存储了两种字幕格式：TTML 和 WebVTT。TTMLPath 属性包含指向 TTML 辅助信息文件的网址，WebVTTPath 属性类似地包含指向 WebVTT 辅助信息文件的网址。
JSON 表示法
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
字段
language string

一种语言代码，例如“en”或“de”。
language_name string

语言的描述性名称。如果同一语言有多个字幕集，则用于区分特定的字幕集
ttml string

TTML 辅助信息文件的可选网址。
webvtt string

WebVTT 辅助信息文件的可选网址。

SkipMetadata

SkipMetadata 提供客户端处理可跳过广告的跳过事件所需的信息。
JSON 表示法
{
  "offset": number,
  "tracking_url": string,
}
字段
offset number

偏移量表示播放器应等待多长时间（以秒为单位）才能呈现“跳过”按钮。如果 VAST 中未提供，则省略。
tracking_url string

TrackingURL 包含一个网址，该网址应在跳过事件发生时被执行 ping 操作。

图标

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，则不包含交易 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。

验证

验证包含 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

一个字符串，用于标识注册库网站的网址，注册库网站中列出了所选广告素材的 Universal Ad 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

相应同伴的 slot 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> 节点的值。