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

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

本指南介绍了如何与 Pod Serving API 交互并实现 IMA DAI SDK 提供类似的功能。对于 请与您的 Google 客户经理联系。

Pod Serving API 支持 Pod 传送 HLS 或 MPEG-DASH 流式传输协议本指南将着重介绍 HLS 视频流，并重点讲解 在具体步骤中，HLS 和 MPEG-DASH 之间的差异。

如需将 Pod Serving API 集成到您的应用中以进行 VOD 视频流，请完成 操作步骤：

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

向数据流注册端点发出 POST 请求。您又会收到 包含要发送到您的清单操作的数据流 ID 的 JSON 响应 和关联的 Pod Serving API 端点

API 端点

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

路径参数

{network_code} 您的 Google Ad Manager 360 广告资源网代码

JSON 正文参数

targeting_parameters 一个包含内容来源 ID (cmsid)、视频 ID (vid) 和 广告定位 参数。必需

响应 JSON

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

示例请求 (c网址)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

示例响应

{
  "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 响应并存储相关值。

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

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

一般来说，您需要传递由 上面的注册端点添加到清单操纵器中，以进行构建 会话专用清单除非您的清单明确说明 您的清单请求的响应是一个视频流，其中包含 内容和广告

示例请求 (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 一组键值对，其中包含出现在 。键可以是广告事件的前 17 个字符 在视频流的定时元数据中显示的 ID（如果是活动） 类型为 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 中找到的值匹配的广告插播时间点 ID 以及上面列出的 ads 对象。每个值都是一个对象 包含以下参数：
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 事件发送 代码。每个相关的电子邮件框的 scheme_id_uri 值要么是 https://aomedia.org/emsg/ID3 或 https://developer.apple.com/streaming/emsg-id3 和 message_data 值 以 ID3TXXXgoogle_ 开头。此 message_data 值不含 ID3TXXX 前缀，即广告事件 ID。

电子邮件框示例

数据结构可能会有所不同，具体取决于您的媒体播放器库。

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

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

某些媒体播放器库会自动显示模拟 ID3 的 emsg 事件 代码转换为原生 ID3 代码。在这种情况下，MP4 视频流会显示相同的 ID3 标记。 为 MPEG_TS。

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

每个广告事件 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

每次有广告事件发生时，都必须向 Ad Manager 发送媒体验证 ping 非 progress 类型的消息。

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

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

示例请求 (c网址)

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

成功响应示例

HTTP/1.1 202 Accepted

其他资源