通过动态广告插播 (DAI) API,您可以在不支持 IMA SDK 的设备上(例如在智能电视上)访问获利视频流。在可以使用 IMA 的平台上,必须使用用 IMA。该 API 支持所有现有的 DAI 功能,但需要发布商实现这些功能。
使用 API 时的要求
发布商在使用 API 时需要实现以下功能:
- 通过 HTTP 端点访问 DAI 视频流以及处理 JSON 响应
- 构建 API 参数和定位键值对
- 实现用户体验(例如,点击后到达网址和图标)
- 监听播放器中的 ID3 事件,以便同时针对线性直播和 VOD 实现播放器控件和广告跟踪/衡量功能
- 实现拖动行为、跳回和书签功能
- 选择流式传输格式:HLS 或 DASH
您可以利用以下信息,了解如何通过 API 为视频点播或线性直播视频流请求和处理视频流。
视频点播 (VOD)
VOD API 遵循一个简单的生命周期,该生命周期始于视频流创建,终于广告播放验证:
-
使用内容来源 ID (
cmsid
) 和视频 ID (vid
)、API 密钥或 HMAC 令牌以及广告定位参数,通过 HTTP POST 请求视频流。https://dai.google.com/ondemand/v1/hls/content/<内容 ID>/vid/<视频 ID>/stream
-
处理对内容播放清单、字幕、广告插播时间点和内容时间信息的响应。
{
"content_duration": 123.451,
"stream_manifest": "https://dai.google.com/.../master.m3u8",
"media_verification_url": "https://dai.google.com/.../media/",
"stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0",
"total_duration": 163.451,
"valid_for": "8h0m0s",
"valid_until": "2018-05-16T23:21:16.558053292-07:00",
"ad_breaks": [...]
}
-
对于每个广告插播时间点,处理点击后到达网址、随播广告素材和广告插播时长信息等广告元素的各项广告详情,以便在界面上呈现。
{
"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400",
"description": "Example pre-roll ad",
"duration": 10,
"seq": 1,
"title": "Example pre-roll"
}
-
针对每个广告,通过广告媒体播放后附加的 ID3 值触发
media_verification_url
。https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
提供 Progress 事件是为了区分广告插播时间点之内和之外的播放,而非用于任何其他广告跟踪目的。
您可以通过在元数据 JSON 文件中搜索媒体标识符来找出 Progress 事件,并验证 type
字段是否已设为 progress
。例如,Progress ID3 可用于屏蔽视频控件。
线性直播视频流
线性 API 遵循一个简单的生命周期,该生命周期始于视频流创建,终于广告播放验证:
-
使用事件 ID、API 密钥或 HMAC 令牌以及广告定位参数,通过 HTTP POST 请求视频流。
https://dai.google.com/linear/v1/hls/event/<事件 ID>/stream
https://dai.google.com/linear/v1/dash/event/<事件 ID>/stream -
处理对内容播放清单、字幕、广告插播时间点和内容时间信息的响应。
{
"stream_manifest": "https://dai.google.com/linear/.../master.m3u8",
"media_verification_url": "https://dai.google.com/linear/.../media/",
"metadata_url": "https://dai.google.com/linear/.../metadata",
"polling_frequency": 10,
"stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",
}
-
按轮询频率请求广告元数据,或按每个 ID3 广告媒体 ID 请求广告元数据(将广告媒体 ID 附加到查询参数中的元数据网址)。
{
"ad_breaks": {
"0001127859": {
"ads": 3,
"duration": 30,
"type": "mid"
}
},
"ads": {
"0001127859_ad2": {
"ad_break_id": "0001127859",
"ad_id": "39135088",
"ad_system": "GDFP",
"clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...",
"creative_id": "103990016608",
"description": "Example linear 10s ad",
"duration": 10,
"position": 2,
"title": "Example linear ad"
}
},
"tags": {
"google_0028792773": {
"ad": "0001127859_ad2",
"ad_break_id": "0001127859",
"type": "firstquartile"
}, ...
}
}
-
针对每个广告,通过广告媒体播放后附加的 ID3 值触发
media_verification_url
。https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
提供 Progress 事件是为了区分广告插播时间点之内和之外的播放,而非用于任何其他广告跟踪目的。
您可以通过在元数据 JSON 文件中搜索媒体标识符来找出 Progress 事件,并验证 type
字段是否已设为 progress
。例如,Progress ID3 可用于屏蔽视频控件。
使用 DAI API 检测广告插播在视频流中何时开始/结束
DAI 会将四分位事件(例如“开始”“第一个四分位”“中点”“第三个四分位”和“完成”)的 ID3 元数据插入广告细分,并将进度事件插入广告和可选广告细分(每秒一次)。首次观察到任何此类 ID3 代码时,可能会触发“广告插播已开始”事件。之后,如果超过比如 2.5 秒后仍未遇到此类 ID3 代码,则可能会触发“广告插播已结束”。插入 DAI 的 ID3 代码可通过其“google_
”前缀及其在元数据 JSON 文件中的存在情况来识别。
动态更新每个用户视频流的定位条件和/或键值对
session_update_url
可用于替换即将针对直播视频流发出的广告请求使用的所有广告代码参数(类似于 replaceAdTagParameters
)。如果定位信息需要按节目及用户进行更新(例如,对于可能无法预先得知定位信息的体育直播),此参数会非常有用。