本指南介绍了如何开发客户端应用,以便通过广告连播投放 API 和清单操纵器加载 HLS 或 DASH 直播。
前提条件
在继续操作之前,您必须满足以下条件:
为采用
Pod serving redirectDAI 类型的直播活动配置的自定义素材资源键。如需获取此密钥,请按以下步骤操作:使用 SOAP API 客户端库调用
LiveStreamEventService.createLiveStreamEvents方法,并提供LiveStreamEvent对象,同时将dynamicAdInsertionType属性设置为POD_SERVING_REDIRECT枚举值。如需查看所有客户端库,请参阅客户端库和示例代码。
确定互动式媒体广告 (IMA) SDK 是否适用于您的平台。我们建议您使用 IMA SDK 来提高收入。如需了解详情,请参阅设置 IMA DAI SDK。
发出流式传输请求
当用户选择直播时,请执行以下操作:
向直播服务方法发出
POST请求。如需了解详情,请参阅方法:stream。以
application/x-www-form-urlencoded或application/json格式传递广告定位参数。此请求会向 Google DAI 注册直播会话。以下示例会发出流式传输请求:
表单编码
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const params = new URLSearchParams({ cust_params: 'section=sports&page=golf,tennis' }).toString(); const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); console.log(await response.json());JSON 编码
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cust_params: { section: 'sports', page: 'golf,tennis' } }) }); console.log(await response.json());如果成功,您会看到如下所示的输出:
{ "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS", "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/", "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata", "session_update_url": "https://dai.google.com/linear/.../session", "polling_frequency": 10 }在 JSON 响应中,找到直播会话 ID 并存储其他数据,以供后续步骤使用。
轮询广告元数据
如需轮询广告元数据,请执行以下操作:
从直播注册响应中读取
metadata_url值。向
metadata_url端点发出初始GET请求。- 省略
delta_token查询参数。通过此过程,服务器可以返回直播的数字视频录像机 (DVR) 时间范围的完整元数据。DVR 时间范围包含观看者可回放和播放的直播时间范围。回答包含next_delta_token字段。
- 省略
为了优化带宽,请存储最新响应中的
next_delta_token值。在下次请求时,将该值作为
delta_token查询参数发送。服务器仅返回自该令牌生成以来发生更改的元数据。请始终发送您收到的最新令牌。 请勿尝试解析、修改或构建令牌。如需了解详情,请参阅方法:metadata。以下示例会提取广告元数据:
// Initial request (returns full metadata and next_delta_token) let response = await fetch(metadata_url); let metadata = await response.json(); let deltaToken = metadata.next_delta_token; // Subsequent request (returns only changes since deltaToken) if (deltaToken) { const url = new URL(metadata_url); url.searchParams.append('delta_token', deltaToken); response = await fetch(url.toString()); const deltaMetadata = await response.json(); // Merge deltaMetadata into your local cache mergeMetadata(metadata, deltaMetadata); deltaToken = deltaMetadata.next_delta_token; }如果成功,您会收到 PodMetadata 响应。如果您提供
delta_token参数,则响应仅包含自服务器生成令牌以来服务器添加或更新的广告、广告插播时间点和代码。响应还包含一个新的next_delta_token值。如果任何广告插播时间点已过时,响应还会包含一个obsolete_ad_break_ids列表,其中列出了要从缓存中移除的广告插播时间点。{ "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0", "obsolete_ad_break_ids": ["0003069407"], "tags":{ "google_1022389921":{ "ad":"0003069408_ad1", "ad_break_id":"0003069408", "type":"start" }, ... }, "ads":{ "0003069408_ad1":{ "ad_break_id":"0003069408", "position":1, "duration":10.01, "title":"External - Pod Midroll 1", "clickthrough_url":"https://.../", ... }, ... }, "ad_breaks":{ "0003069408":{ "type":"mid", "duration":30, "ads":3 }, ... } }保存
tags对象,并将更新合并到本地缓存中。如果存在obsolete_ad_break_ids参数,请从缓存中移除这些广告插播时间点以及关联的广告和代码。使用
polling_frequency值设置一个计时器,以定期请求元数据。在每次轮询中,将最近的元数据响应中返回的next_delta_token值作为delta_token查询参数发送。
将直播加载到视频播放器中
从注册响应中获取会话 ID 后,将该 ID 传递给清单操纵器,或构建清单网址以将视频流加载到视频播放器中。
如需传递会话 ID,请参阅清单操纵器文档。如果您开发清单操纵器,请参阅适用于直播的清单操纵器。
以下示例组装了一个清单网址:
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
播放器准备就绪后,开始播放。
监听广告事件
检查直播流的容器格式是否支持定时元数据:
具有传输流 (TS) 容器的 HLS 视频流使用定时 ID3 标签来承载定时元数据。如需了解详情,请参阅关于采用 HTTP Live Streaming (HLS) 的通用媒体应用格式。
DASH 视频流使用
EventStream元素在清单中指定事件。当分段包含用于载荷数据(包括 ID3 标记)的事件消息 (
emsg) 框时,DASH 视频流会使用InbandEventStream元素。如需了解详情,请参阅 InbandEventStream。CMAF 流(包括 DASH 和 HLS)使用包含 ID3 标签的
emsg框。
如需从直播中检索 ID3 标签,请参阅视频播放器指南。如需了解详情,请参阅处理定时元数据指南
如需从 ID3 标签中检索广告事件 ID,请执行以下操作:
- 使用
urn:google:dai:2018或https://aomedia.org/emsg/ID3按scheme_id_uri过滤事件。 从
message_data字段中提取字节数组。以下示例将
emsg数据解码为 JSON:{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }使用以下格式过滤 ID3 标签:
TXXXgoogle_{ad_event_ID}TXXXgoogle_1022389921
显示广告事件数据
如需查找 TagSegment 对象,请执行以下操作:
从轮询广告元数据中检索广告元数据
tags对象。tags对象是TagSegment对象数组。使用完整的广告事件 ID 查找类型为
progress的TagSegment对象。使用广告事件 ID 的前 17 个字符查找其他类型的
TagSegment对象。由于客户端应用会定期轮询广告元数据,因此在视频播放器遇到视频流中的 ID3 标签与关联元数据可用之间可能会出现延迟。如果您的客户端应用在存储的代码中未找到 ID3 代码,请将该代码保留在队列中,并在下次元数据轮询后重新处理该代码。将代码保留在队列中,直到处理完成。
获得
TagSegment后,使用ad_break_id属性作为键,在广告元数据ad_breaks对象中查找AdBreak对象。以下示例会查找
AdBreak对象:{ "type":"mid", "duration":15, "ads":1 }使用
TagSegment和AdBreak数据显示有关广告插播时间点中广告排名的信息。例如Ad 1 of 3。
发送媒体验证 ping
对于除 progress 类型之外的每个广告事件,请发送媒体验证 ping。
Google DAI 会舍弃 progress 事件,频繁发送这些事件可能会影响应用性能。
如需生成广告事件的完整媒体验证网址,请执行以下操作:
从直播响应中,将完整广告事件 ID 附加到
media_verification_url值。使用完整网址发出
GET请求:// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);如果成功,您会收到代码状态为
202的响应。否则,您会收到404错误代码。
您可以使用视频流活动监控工具 (SAM) 检查所有广告事件的历史日志。如需了解详情,请参阅监控直播并排查直播问题