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

此页面由 Cloud Translation API 翻译。

动态广告插播线性 API

借助 Dynamic Ad Insert API，您可以请求和跟踪 DAI 线性 (LIVE) 直播。

服务：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 密钥，而是可以传递 API 密钥，并采用以下格式： Authorization: DCLKDAI key="<api-key>"

api‑key

string

创建视频流时提供的 API 密钥必须对发布商的广告联盟有效。

您无需在请求正文中提供 API 密钥，而是可以传递 API 密钥，并采用以下格式：

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

路径参数

参数
`assetKey`	`string` 数据流的事件 ID。注意：直播资产键是一种标识符，同样可以在以下位置找到： <ph type="x-smartling-placeholder"></ph> Ad Manager 界面。

请求正文

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

参数
`dai-ssb`	可选	设置为 `true` 可创建服务器端信标流。默认值为 `false`。默认视频流的跟踪指标由客户端启动，并在服务器端执行 ping 操作。
DFP 定位参数	可选	<ph type="x-smartling-placeholder"></ph> 其他定位参数。
替换数据流参数	可选	<ph type="x-smartling-placeholder"></ph> 替换数据流创建参数的默认值。
HMAC 身份验证	可选	<ph type="x-smartling-placeholder"></ph> 使用基于 HMAC 的令牌进行身份验证。

响应正文

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

开放式衡量

DAI API 在 Verifications 字段。此字段包含一个或多个 Verification 元素，用于列出执行所需的资源和元数据第三方衡量代码，以验证广告素材播放。仅限支持 JavaScriptResource。如需了解详情，请参阅 IAB Tech Lab 和 VAST 4.1 规范。

方法：媒体验证

在播放过程中遇到广告媒体标识符后，立即使用从视频流中获取的 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)

系统将使用键在 HLS 定时元数据中对广告媒体标识符进行编码 TXXX，预留给“用户定义的文本信息”帧。通过帧的内容不会加密，并且始终以 "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` 请求 metadata_url 或 heartbeat_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广告媒体验证端点。

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,
  "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` 所有 <Extension> 的可选列表节点。
`companions`	`[object(Companion)]` 可与此广告一起展示的可选随播广告。
`interactive_file`	`object(InteractiveFile)` 应在广告播放过程中展示的可选互动式广告素材 (SIMID)。

图标

图标包含有关 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（如果不存在）。

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` 用于标识包含所选广告素材的通用广告 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` <StaticResource> 上的 CreativeType 属性节点中这是 static 类型的随播广告。
`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` <AdParameters> 的值节点。

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

服务：dai.google.com

方法：stream

HTTP 请求

请求标头

路径参数

请求正文

响应正文

开放式衡量

方法：媒体验证

HTTP 请求

响应正文

广告媒体 ID (HLS)

方法：metadata

HTTP 请求

响应正文

使用元数据

响应数据

数据流

PodMetadata

TagSegment

AdBreak

广告

图标

ClickData

FallbackImage

Wrapper

验证

JavaScriptResource

TrackingEvent

UniversalAdID

随播广告

InteractiveFile

动态广告插播线性 API