DAI API 目前处于 Beta 版阶段，在您的广告资源网中可能无法使用。如需了解详情，请与您的客户经理联系。我们建议在提供 IMA SDK 的平台上使用该 SDK。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

动态广告插播线性 API

借助动态广告插播 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>"

api‑key

string

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

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

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

路径参数

参数
`assetKey`	`string` 相应直播的活动 ID。注意：视频流素材资源键也是一个标识符，可在 Ad Manager 界面中找到。

请求正文

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

参数
`dai-ssb`	可选	设置为 `true` 可创建服务器端信标流。默认值为 `false`。默认流的跟踪由客户端发起，并在服务器端进行 ping 操作。
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。
HTTP/1.1 404 Not Found 如果之前针对相应 ID 的验证请求成功完成。
HTTP/1.1 409 Conflict 如果此时另一个请求已在发送 ping。

广告媒体 ID (HLS)

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

在发出每个广告验证请求之前，应将框架的整个文本内容附加到广告验证网址。

方法：元数据

位于 metadata_url 的元数据端点会返回用于构建广告界面 (UI) 的信息。元数据端点不适用于服务器端信标传送流，在这种情况下，服务器负责启动广告媒体验证。

方法
`metadata`	`GET /{metadata_url}/{ad-media-id}` `GET /{metadata_url}` 检索广告元数据信息。

HTTP 请求

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

查询参数

参数
`delta_token`	可选	`string` 表示客户端当前同步状态的不透明令牌。如果提供了此参数，服务器将仅返回自令牌生成以来发生更改的元数据，并在响应中返回新的 `next_delta_token`。如果省略，服务器会返回整个 DVR 时间范围的完整元数据。

响应正文

如果成功，响应会返回一个 PodMetadata 实例。

使用元数据

元数据包含三个不同的部分：tags、ads 和广告 breaks。数据的入口点是 tags 部分。然后，遍历这些标记，找到名称是视频流中找到的广告媒体 ID 的前缀的第一个条目。例如，您可能有一个如下所示的广告媒体 ID：

google_1234567890

然后，您会找到一个名为 google_12345 的标记对象。在这种情况下，它与您的广告媒体 ID 相匹配。找到正确的广告媒体前缀对象后，您可以查找广告 ID、广告插播时间点 ID 和事件类型。然后，使用广告 ID 为 ads 对象编制索引，并使用广告插播时间点 ID 为 breaks 对象编制索引。

响应数据

数据流

Stream 用于以 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` 请求 metadata_url 或 heartbeat_url 时的轮询频率（以秒为单位）。

PodMetadata

PodMetadata 包含有关广告、广告插播时间和媒体 ID 标记的元数据信息。

JSON 表示法
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], "next_delta_token": string, "obsolete_ad_break_ids": [], }

字段
`tags`	`map[string, object(TagSegment)]` 按标记前缀索引的标记段的映射。
`ads`	`map[string, object(Ad)]` 按广告 ID 编制索引的广告映射。
`ad_breaks`	`map[string, object(AdBreak)]` 按广告插播时间点 ID 编制索引的广告插播时间点地图。
`next_delta_token`	`string` 供客户端在下次轮询时使用的不透明令牌。
`obsolete_ad_break_ids`	`string` 已过时且应从客户端缓存中移除的广告插播时间点 ID 的列表。

TagSegment

TagSegment 包含对广告、广告插播时间点和事件类型的引用。不应向广告媒体验证端点 ping 类型为“progress”的 TagSegment。

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` 广告插播时间点中的广告数量。

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,
  "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)]` 可选的开放式衡量验证条目，其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。
`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, }

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)], }

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> 节点的值。

动态广告插播线性 API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

服务：dai.google.com

方法：stream

HTTP 请求

请求标头

路径参数

请求正文

响应正文

开放式衡量

方法：媒体验证

HTTP 请求

响应正文

广告媒体 ID (HLS)

方法：元数据

HTTP 请求

查询参数

响应正文

使用元数据

响应数据

数据流

PodMetadata

TagSegment

AdBreak

广告

图标

ClickData

FallbackImage

Wrapper

验证

JavaScriptResource

TrackingEvent

UniversalAdID

随播广告

InteractiveFile

动态广告插播线性 API