适用于直播的动态动态广告插入 API

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

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

  • 三星智能电视 (Tizen)
  • LG 电视
  • HbbTV
  • Xbox(JavaScript 应用)
  • KaiOS

该 API 支持 IMA DAI SDK 提供的基本功能。有关兼容性或受支持功能的具体问题,请与您的 Google 客户经理联系。

为直播直播实现 DAI API

DAI API 支持使用 HLS 和 DASH 协议的线性 (LIVE) 视频流。 本指南中介绍的步骤同时适用于这两种协议。

如需将该 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":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

错误响应

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

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

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

2. 轮询新的 AdBreak 元数据

设置计时器,以使用元数据网址以轮询频率轮询新的 AdBreak 元数据。如果未在数据流响应中指定,则默认建议间隔为 10 秒。

示例请求正文

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

响应正文示例

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

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

如需验证视频流中是否发生了特定事件,请按照以下步骤处理 ID3 事件:

  1. 将媒体事件存储在队列中,同时保存每个媒体 ID 及其时间戳(如果播放器显示的话)。
  2. 每次从播放器进行更新时,或者以设定的频率(建议 500 毫秒)更新时,通过将事件时间戳与进度条指针进行比较,检查媒体事件队列中是否有最近播放的事件。
  3. 对于您确认已播放的媒体事件,请通过在存储的广告插播时间点标记中查找媒体 ID 来检查类型。请注意,存储的代码仅包含媒体 ID 的前缀,因此无法实现完全匹配。
  4. 使用“progress”事件来跟踪用户是否处于广告插播时间点。请勿将这些事件发送到媒体验证端点。对于其他事件类型,请将媒体 ID 附加到媒体验证端点,并发出 GET 请求以跟踪播放。
  5. 从队列中移除媒体事件。

示例请求正文

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

示例回复

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/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

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

响应正文示例

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

限制

如果在 WebView 中使用 API,则在定位方面存在以下限制:

  • 用户代理:用户代理参数作为浏览器专用值传递,而不是作为底层平台传递。
  • rdididtypeis_lat:未正确传递设备 ID,导致以下功能的功能受到限制:
    • 频次上限
    • 依序轮播广告
    • 受众群细分和定位

最佳实践

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

其他资源