借助 Dynamic Ad Placement API,您可以请求和跟踪 DAI 线性(直播)视频流。
服务:dai.google.com
以下所有 URI 都是 https://dai.google.com
的相对路径
方法:数据流
方法 | |
---|---|
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 授权标头中传递,格式如下,而不是在请求正文中提供该 API 密钥: Authorization: DCLKDAI key="<api-key>" |
路径参数
参数 | |
---|---|
assetKey |
string 数据流的事件 ID。 |
请求正文
请求正文的类型为 application/x-www-form-urlencoded
,包含以下参数:
参数 | ||
---|---|---|
dai-ssb |
选填 | 设置为 |
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
。 - 如果之前针对此 ID 的验证请求成功,则为
HTTP/1.1 404 Not Found
。 - 如果此时有另一个请求已在发送 ping,则为
HTTP/1.1 409 Conflict
。
广告媒体 ID (HLS)
广告媒体标识符将使用键 TXXX
在 HLS 定时元数据中编码,该键为“用户定义的文本信息”帧预留。帧的内容不会加密,并且始终以文本 "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 执行 ping 操作,将其连接到广告媒体验证端点。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 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, } |
字段 | |
---|---|
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。 |
验证
Verification 包含 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 VAST 中 <StaticResource> 节点上的 CreativeType 属性(如果相应广告素材是静态类型的随播广告素材)。 |
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 VAST 中 <AdParameters> 节点的值。 |