管理 DAI 直播

借助 Google DAI API，您可以在不支持实现 IMA SDK 的环境中实现启用 Google DAI 的视频流。我们建议您在支持 IMA SDK 的平台上仍使用 IMA。

我们建议在以下平台上使用 DAI API：

  • Samsung 智能电视 (Tizen)
  • LG TV
  • HbbTV
  • Xbox（JavaScript 应用）
  • KaiOS

该 API 支持 IMA DAI SDK 提供的基本功能。如果您对兼容性或支持的功能有具体疑问，请与您的 Google 客户经理联系。

为直播实现 DAI API

DAI API 支持使用 HLS 和 DASH 协议的线性（直播）视频流。本指南中介绍的步骤适用于这两种协议。

如需将该 API 集成到您的直播应用中，请完成以下步骤：

1. 请求直播

如需通过 DAI API 请求直播，请向流端点发出 POST 调用。JSON 响应包含视频流清单以及关联的 DAI API 端点和值。

请求正文示例

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

响应正文示例

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

错误响应

如果发生错误，系统会返回标准 HTTP 错误代码，但不包含 JSON 响应正文。

解析 JSON 响应并存储以下值：

stream_id
此值可用于标识返回的流。
stream_manifest
此网址会传递给媒体播放器，用于播放视频流。
media_verification_url
此网址是用于跟踪播放事件的基本端点。
metadata_url
此网址用于轮询有关即将到来的直播活动的定期信息。
session_update_url
此网址用于更新在初始视频流请求期间发送的视频流请求参数。请注意，此请求的参数会替换为之前流设置的所有参数。
polling_frequency
从 DAI API 请求更新后的广告插播元数据的频率（以秒为单位）。

2. 轮询新的 AdBreak 元数据

设置一个定时器，以使用元数据网址按轮询频率轮询新的广告插播元数据。如果未在流响应中指定，则建议的默认间隔为 10 秒。

如需优化带宽，请执行以下操作：

  1. 向 metadata_url 端点发出初始 GET 请求。
    • 省略 delta_token 查询参数。此过程可让服务器返回直播的数字视频录像机 (DVR) 时间范围的完整元数据。DVR 窗口包含可供观看者回放和播放的广播时间范围。响应包含 next_delta_token 对象字段。
  2. 在客户端存储元数据。
  3. 使用最新响应返回的 next_delta_token 值进行后续调用。每个响应都包含一个 next_delta_token 值。始终发送您收到的最新值。
  4. 更新存储的元数据，以合并更改并移除过时的广告插播时间。

请勿尝试解析、构建或修改增量令牌。令牌的格式可能会发生变化。按原样存储令牌，并在下一个请求中按原样传递令牌。

初始请求示例

初始请求不带任何查询参数，并返回完整的元数据：

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

后续请求示例

每个后续请求都会将上一个响应中的 next_delta_token 值作为 delta_token 参数传递。响应包含以下内容：

  • Ads
  • 广告插播时间点
  • 自服务器发出令牌以来，服务器添加或更新的标记。
  • 要从存储的元数据中移除的广告插播时间点的 obsolete_ad_break_ids 列表

服务器会省略未发生变化的广告插播时间。以下示例展示了如何使用增量令牌进行后续轮询，以仅提取这些近期更改：

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

如果成功，您将看到类似于以下内容的输出：

{
   "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",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. 监听 ID3 事件并跟踪播放事件

如需验证视频流中是否发生了特定事件，请按以下步骤操作来处理 ID3 事件：

  1. 将媒体事件存储在队列中，并保存每个媒体 ID 及其时间戳（如果由播放器显示）。
  2. 在每次播放器更新时间时，或以设定的频率（建议为 500 毫秒）检查媒体事件队列，通过将事件时间戳与进度条指针进行比较，查看最近播放的事件。
  3. 对于您确认已播放的媒体事件，请通过在存储的广告插播时间点代码中查找媒体 ID 来检查其类型。请注意，存储的标记仅包含媒体 ID 的前缀，因此无法实现完全匹配。
  4. 由于视频播放器应用会定期轮询元数据网址，因此视频播放器在视频流中遇到 ID3 标记与相关元数据可用之间可能会出现延迟。如果在存储的标记中未找到 ID3 标记，则将该标记保留在队列中，并在下一次元数据轮询后重新处理该标记。将事件保留在队列中，直到处理完成。
  5. 在元数据中找到代码后，请根据下一部分中列出的广告事件类型检查代码的 type 字段。如需跟踪视频播放器是否正在播放广告插播时间点，请使用 type 字段中值为 progress 的事件。请勿将这些事件发送到媒体验证端点。对于所有其他事件类型，请将媒体 ID 附加到媒体验证端点，并发出 GET 请求来跟踪播放情况。
  6. 从队列中移除媒体事件。

广告事件类型

元数据 tags 对象中的每个标记都具有以下事件类型之一：

事件类型 说明
start 在广告开头播放。
firstquartile 在广告的第一个四分之一处结束时运行。
midpoint 在广告展示过程的中间运行。
thirdquartile 在广告的第三个四分位结束时运行。
complete 在广告结束时运行。
progress 在广告插播时间点期间定期运行，以表明正在播放广告插播。请勿将这些事件发送到媒体验证端点。

示例请求

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

示例回复

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

您可以在视频流活动监控工具中验证跟踪事件。

4. 更新直播会话参数

您可能需要在创建流后调整会话参数。为此，请向会话更新网址发出请求。

请求正文示例

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

响应正文示例

Successful response would be to look for - HTTP/1.1 200

限制

如果在 WebView 中使用该 API，则在定位方面存在以下限制：

  • UserAgent：用户代理参数作为特定于浏览器的值（而非底层平台）传递。
  • rdid、idtype、is_lat：设备 ID 未正确传递，这会限制以下功能：
    • 频次上限
    • 依序轮播广告
    • 受众群细分和定位

最佳做法

请注意，直播索引的元数据端点基于相应 ID3 标记的前缀。这是有意为之，旨在防止使用元数据端点立即 ping 所有验证节点。

其他资源