Pod Serving API 目前处于封闭式 Beta 版测试阶段。如果您有兴趣详细了解 Pod Serving 或想要实现 Pod Serving API，请与您的 Google 客户经理联系。

此页面由 Cloud Translation API 翻译。

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

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

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

Pod Serving API 支持 HLS 或 MPEG-DASH 流式传输协议中的连播提取内容流。本指南重点介绍 HLS 串流，并通过具体步骤突出 HLS 和 MPEG-DASH 之间的主要区别。

如需将 Pod Serving API 集成到您的应用中以提供 VOD 串流，请完成以下步骤：

向 Ad Manager 发出数据流注册请求

向串流注册端点发出 POST 请求。您会收到一个 JSON 响应，其中包含要发送到清单处理服务器和关联的 Pod Serving API 端点的串流 ID。

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 包含广告定位参数的 JSON 对象。必填

响应 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 \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 响应并存储相关值。

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

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

通常，您需要将上述注册端点返回的串流 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

一组键值对，用于描述直播中显示的所有广告插播。键是广告插播 ID，与上文中列出的 tags 和 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 事件发送。每个相关的 emsg 框的 scheme_id_uri 值均为 https://aomedia.org/emsg/ID3 或 https://developer.apple.com/streaming/emsg-id3，message_data 值以 ID3TXXXgoogle_ 开头。此 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 对象中的键匹配。匹配这些值的过程分为两个步骤：

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

如果未找到与完整广告事件 ID 匹配的键，请检查 tags 对象，看看是否有与广告事件 ID 的前 17 个字符匹配的键。检索事件类型以及关联的 ad 和 ad_break 对象。这应检索类型为 progress 以外的所有事件。
使用检索到的信息更新玩家的界面。例如，当您收到 start 或第一个 progress 事件时，请隐藏播放器的快进控制，并显示一个叠加层，用于说明当前广告在广告插播中的展示位置，例如“广告 1 / 3”。

广告事件 ID 示例

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

示例 tags 对象

{
  "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

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

向 Ad Manager 发出数据流注册请求

API 端点

路径参数

JSON 正文参数

响应 JSON

请求示例 (c网址)

示例响应

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

请求示例 (c网址)

响应示例 (HLS)

播放数据流

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

请求示例 (c网址)

示例响应

监听广告事件

ID3 代码示例

emsg 框示例

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

广告事件 ID 示例

示例 tags 对象

发送媒体验证 ping

请求示例 (c网址)

成功响应示例

其他资源