动态广告插播线性 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>"

路径参数

参数
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_idstream_manifest 字段。

开放式衡量

DAI API 在 Verifications 字段。此字段包含一个或多个 Verification 元素,用于列出执行所需的资源和元数据 第三方衡量代码,以验证广告素材播放。仅限 支持 JavaScriptResource。如需了解详情,请参阅 IAB Tech LabVAST 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

使用元数据

元数据有三个独立的部分:tagsads 和广告 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

此广告的广告插播时间点的 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,
}
字段
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)],
}
字段
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> 的值节点。