动态广告插播广告连播投放实时 API

借助 Dynamic Ad Insert API，您可以请求和跟踪 DAI 直播。

服务：dai.google.com

所有 URI 均相对于 https://dai.google.com。

方法：stream

方法
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

注册提供直播会话的 DAI DAI Pod。

HTTP 请求

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

路径参数

参数
network_code string

发布商的 Google Ad Manager 广告资源网代码。

custom_asset_key string

Google Ad Manager 中与此事件相关联的自定义标识符。

请求正文

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

参数
DFP 定位参数 可选 <ph type="x-smartling-placeholder"></ph> 其他定位参数。
替换数据流参数 可选 <ph type="x-smartling-placeholder"></ph> 替换数据流创建参数的默认值。
HMAC 身份验证 可选 <ph type="x-smartling-placeholder"></ph> 使用基于 HMAC 的令牌进行身份验证。

响应正文

如果成功，响应正文将包含一个新的 Stream 对象。

开放式衡量

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

方法：广告连播细分

方法
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

为指定的事件 ID 创建 DAI 视频流。

HTTP 请求

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

路径参数

参数
network_code string

发布商的 Google Ad Manager 广告资源网代码。

custom_asset_key string

Google Ad Manager 中与此事件相关联的自定义标识符。

pod_id integer

当前广告插播时间点的数字标识符。广告连播 ID 包括 从 1 开始递增分配。

<ph type="x-smartling-placeholder">
profile_name string

通过 名称 的 Google Ad Manager DAI 编码配置文件。 编码配置文件必须是已配置的编码配置文件之一， 所选活动

segment_number integer

当前广告连播中所请求的细分受众群的索引，从 零。

<ph type="x-smartling-placeholder">
segment_format string

与请求的片段格式相关联的文件扩展名。 接受的附加信息包括：ts、mp4、 vtt、aac、ac3 或 eac3。

查询参数

参数
stream_id 必需 string

当前用户会话的视频流 ID。该值由 向 stream 端点发送成功的请求。
sd required1 integer

所请求的片段的时长（以毫秒为单位）。
so 可选

所请求的片段在广告连播中的偏移量（以毫秒为单位）。 如果您省略 so 参数，其计算方式如下： 用片段时长乘以片段编号
pd 必需2 integer

广告连播的时长（以毫秒为单位）。
auth-token 必需 string

经过签名的网址编码 HMAC 令牌 当前广告连播的频次上限
last 可选 boolean

表示广告插播时间点的最后一个片段。对于所有项目，都省略此参数 其他细分受众群
scte35 可选 string

此广告插播时间点的 Base64 编码 SCTE-35 信号。
cust_params 可选 string

一组用于 Ad Manager 广告系列定位的键值对。这些 对必须表示为网址编码查询字符串。

示例：
参数
  • section = sports
  • 网页 = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

脚注

  1. 初始化细分不需要 sd。 ↩
  2. 对于包含无时长广告的活动，无需设置 pd 断点。 ↩

响应正文

如果成功，响应正文将是一个与 请求中指定的格式和参数。

方法：DASH Pod 时段模板

方法
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

从 Google Ad Manager 请求 DASH 时段模板。此模板 包含您必须使用视频流参数填充的宏。一次 系统会填充这些宏，模板将成为广告插播时间段， 可拼接到 DASH 清单中。

<ph type="x-smartling-placeholder">

HTTP 请求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

路径参数

参数
network_code string

发布商的 Google Ad Manager 广告资源网代码。

custom_asset_key string

Google Ad Manager 中与此事件相关联的自定义标识符。

查询参数

参数
stream_id 必需 string

当前用户会话的视频流 ID。该值由 向 stream 端点发送成功的请求。

响应正文

如果成功，响应正文将包含一个新的 PodTemplateResponse 对象。

方法：媒体验证

在播放过程中遇到广告媒体标识符后，立即 使用从视频流中获取的 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 提出的验证请求） 成功。
  • 如果已有其他请求在此位置发送 ping，则为 HTTP/1.1 409 Conflict 。

广告媒体 ID

广告媒体标识符将在单独的有时间限制的元数据轨道中编码 元数据，对于 mp4 文件，则为 emsg。广告媒体标识符 始终以字符串 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,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
字段
stream_id string

GAM 视频流标识符。
media_verification_url string

用作跟踪播放事件的基础端点的媒体验证网址。
metadata_url string

用于轮询有关即将进行的直播广告的定期信息的元数据网址。
session_update_url string

用于更新此视频流的定位参数的会话更新网址。 系统会在初始视频流创建请求期间捕获定位参数的原始值。
heartbeat_url string

检测信号网址，用于使服务器端信标流保持活跃状态； 必须每 {PollingFrequency} 秒对其执行一次 ping 操作。 为服务器端信标流填充。
polling_frequency number

请求 metadata_url 或 heartbeat_url 时的轮询频率（以秒为单位）。
pod_manifest_url string

广告连播清单网址模板用于生成网址，以检索视频流的广告连播清单。 对应于 HLS 中的多变体播放列表的网址或 DASH 中的 MPD。 为动态广告插播类型为“POD_SERVING_MANIFEST”的直播活动填充。 https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

清单格式是从 pod_manifest_url 中检索到的清单的格式， dash 或 hls。

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)。

PodTemplateResponse

PodTemplateResponse 表示返回到 VTP 进行 Pod 拼接的 JSON 载荷。
JSON 表示法
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
字段
dash_period_template string

DashPeriodTemplate 是该时间段的 XML 模板，该模板在拼接之前填充了适当的数据。
segment_duration_ms int64

SegmentDurationMS 是时间段片段的时长（以毫秒为单位）。

图标

图标包含有关 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> 的值节点。