用于直播的客户端视频播放器应用

借助 Google DAI Pod Serving API，您可以执行由 Google Ads 提供支持的服务器端广告插播，同时保持对自己视频拼接的控制。

本指南介绍了如何与 Pod Serving API 交互以及如何使用 IMA DAI SDK 实现类似功能。有关受支持功能的具体问题，请与您的 Google 客户经理联系。

Pod Serving API 支持采用 HLS 或 MPEG-DASH 流式传输协议的 Pod 传送数据流。本指南重点介绍 HLS 流并在特定步骤中重点介绍 HLS 和 MPEG-DASH 之间的主要区别。

如需将 Pod Serving API 集成到您的应用以用于 VOD 视频流，请完成以下步骤：

向 Ad Manager 发送视频流注册请求

向数据流注册端点发出 POST 请求。反过来，您会收到一个包含数据流 ID 的 JSON 响应，该 ID 将发送到您的清单操纵服务器和关联的 Pod Serving API 端点。

API 端点

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/json

路径参数

{network_code} 您的 Google Ad Manager 360 广告资源网代码
{custom_asset} 在 Google AdManager 中与此事件关联的自定义标识符。

表单编码的正文参数

一组采用表单编码的可选 定位参数 。

响应 JSON

media_verification_url 用于 ping 播放跟踪事件的基础网址。将广告事件 ID 附加到此基准网址即可形成完整的媒体验证网址。
metadata_url 用于请求广告连播元数据的网址。
stream_id 用于标识当前直播会话的字符串。
valid_for 距离当前流式会话到期的剩余时间，采用 dhms（天、小时、分钟、秒）格式。例如，2h0m0.000s 表示时长为 2 小时。
valid_until 当前流式会话的到期时间，采用 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 格式的 ISO 8601 日期时间字符串。

示例请求 (c网址)

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded"
     -d "cust_params="section%3Dsports%26page%3Dgolf%2Ctennis"
  https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/an-public-test-asset/stream

示例响应

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

如果出现错误，则返回标准 HTTP 错误代码，但没有 JSON 响应正文。

解析 JSON 响应并存储相关值。

从清单操纵器请求数据流清单

每个清单操纵器都有不同的请求和响应格式。请与您的操纵器提供商联系，了解其具体要求。如果您要实现自己的清单操纵器，请参阅清单操纵器指南，了解此组件的要求。

一般来说，您需要将上述注册端点返回的数据流 ID 传递给清单操纵器，以便它构建会话专用清单。除非清单操纵器明确说明，否则对清单请求的响应将是一个同时包含内容和广告的视频流。

示例请求 (c网址)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

示例响应 (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

播放直播

将您从清单操纵服务器收到的清单加载到视频播放器中，然后开始播放。

向 Ad Manager 请求广告连播元数据

向您在第 1 步中收到的 metadata_url 发出 GET 请求。此步骤必须在您从清单操纵器收到拼接后的清单后执行。进而接收包含以下参数的 JSON 对象：

tags 一组键值对，其中包含数据流中显示的所有广告事件。键为在数据流的定时元数据中显示的广告事件 ID 的前 17 个字符；如果是 progress 类型的事件，则为完整的广告事件 ID。

每个值都是包含以下参数的对象：

ad 与 ads 对象中的键匹配的广告的 ID。
ad_break_id 与 ad_breaks 对象中的键匹配的广告插播时间点的 ID。
type 广告事件的类型。广告事件类型包括：
start 在广告开始时触发。
firstquartile 在第一个四分位结束时触发。
midpoint 在广告播放到一半时触发。
thirdquartile 在第三个四分位结束时触发。
complete 在广告结束时触发。
progress 在整个广告中定期触发，用于通知应用正在播放广告插播时间点。
ads 一组键值对，用于描述视频流中显示的所有广告。键是与上面列出的 tags 对象中的值匹配的广告 ID。每个值都是包含以下参数的对象：
ad_break_id 与 ad_breaks 对象中的键匹配的广告插播时间点的 ID。
position 此广告在广告插播时间点内这组广告中的显示位置（以浮点数表示）。
duration 广告的时长（以浮点数秒表示）。
clickthrough_url 用户与此广告互动时应打开的网址（如果支持）。
ad_breaks 一组键值对，用于描述视频流中出现的所有广告插播时间点。键是与上面列出的 tags 和 ads 对象中的值匹配的广告插播时间点 ID。每个值都是包含以下参数的对象：
type 广告插播时间点的类型。广告插播时间点类型为 pre（前贴片广告）、mid（中贴片广告）和 post（后贴片广告）。
duration 广告插播时长（以浮点数表示）。
ads 此广告插播时间点的广告数量。

存储这些值，以与视频流中的定时元数据事件相关联。

示例请求 (c网址)

curl https://dai.google.com/.../metadata

示例响应

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

监听广告事件

通过视频播放器的音频/视频流中触发的广告事件监听定时元数据。

对于 MPEG-TS 流，元数据显示为带内 ID3 v2.3 标记。每个元数据标记都具有 ID TXXX，其值以字符串 google_ 开头，后跟一系列字符。此值就是广告事件 ID。

TXXX 中的 XXX 不是占位符。字符串 TXXX 是为“用户定义的文本”预留的 ID3 代码 ID。

ID3 代码示例

TXXXgoogle_1234567890123456789

对于 MP4 视频流，这些事件会作为模拟 ID3 v2.3 代码的带内 emsg 事件发送。每个相关的 emsgbox 均有一个 scheme_id_uri 值 https://aomedia.org/emsg/ID3 或 https://developer.apple.com/streaming/emsg-id3，以及一个以 ID3TXXXgoogle_ 开头的 message_data 值。这个 message_data 值（不带 ID3TXXX 前缀）是广告事件 ID。

emsg 框示例

数据结构可能会因媒体播放器库而异。

如果广告事件 ID 为 google_1234567890123456789，响应将如下所示：

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

某些媒体播放器库会自动呈现将 ID3 代码模拟为原生 ID3 代码的 emsg 事件。在这种情况下，MP4 流提供与 MPEG_TS 相同的 ID3 标记。

更新客户端视频播放器应用的界面

每个广告事件 ID 都可以与第 4 步中的 tags 对象中的一个键相匹配。匹配这些值的过程分为两个步骤：

  1. 检查 tags 对象中是否有与完整广告事件 ID 匹配的键。如果找到匹配项，则检索事件类型及其关联的 ad 和 ad_break 对象。这些事件的类型为 progress。

    如果未找到与完整广告事件 ID 的匹配项，请检查 tags 对象中是否有与该广告事件 ID 的前 17 个字符匹配的键。检索事件类型以及关联的 ad 和 ad_break 对象。这应该会检索 progress 以外的类型的所有事件。

  2. 使用检索到的信息来更新播放器的界面。例如，当您收到 start 或第一个 progress 事件时，请隐藏播放器的进度滑块控件，并显示一个叠加层来说明当前广告在广告插播时间点中的位置，例如：“广告 1/3”。

广告事件 ID 示例

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

代码对象示例

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

发送媒体验证 ping

每次收到类型不是 progress 的广告事件时，都必须向 Ad Manager 发送媒体验证 ping。

如需生成广告事件的完整媒体验证网址，请将完整的广告事件 ID 附加到数据流注册响应中的 media_verification_url 值。

使用完整网址发出 GET 请求。如果验证请求成功，您会收到状态代码为 202 的 HTTP 响应。否则，您会收到 HTTP 错误代码 404。

示例请求 (c网址)

curl https://{...}/media/google_5555555555123456789

成功响应示例

HTTP/1.1 202 Accepted

其他资源