Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

为广告连播投放重定向做好客户端准备

本指南介绍了如何开发客户端应用，以使用广告连播投放 API 和清单操纵器加载 HLS 或 DASH 直播。

前提条件

在继续操作之前，您必须具备以下条件：

为配置了 Pod serving redirect DAI 类型的直播活动设置的自定义素材资源键。如需获取此密钥，请按以下步骤操作：
- 设置 DAI 直播。
- 使用 SOAP API 客户端库调用 LiveStreamEventService.createLiveStreamEvents 方法，并使用 LiveStreamEvent 对象和设置为 POD_SERVING_REDIRECT 枚举值的 dynamicAdInsertionType 属性。如需查看所有客户端库，请参阅客户端库和示例代码。
确定互动式媒体广告 (IMA) SDK 是否适用于您的平台。我们建议使用 IMA SDK 来提高收入。如需了解详情，请参阅为 DAI 设置 IMA SDK。

发出流式请求

当用户选择某个直播时，请执行以下操作：

向直播服务方法发出 POST 请求。如需了解详情，请参阅方法：stream。

以 application/x-www-form-urlencoded 或 application/json 格式传递广告定位参数。此请求向 Google DAI 注册视频流会话。

以下示例会发出流式请求：

表单编码

const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

JSON 编码

const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

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

{
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

在 JSON 响应中，找到直播会话 ID 并存储其他数据以供后续步骤使用。

重要提示：为确保应用正常运行，请直接使用回答中提供的网址。请勿构建网址，因为路径可能会发生变化。

轮询广告元数据

如需轮询广告元数据，请执行以下操作：

从视频流注册响应中读取 metadata_url 值。
向 metadata_url 端点发出初始 GET 请求。
- 省略 delta_token 查询参数。此过程可让服务器返回直播的数字视频录像机 (DVR) 时间范围的完整元数据。DVR 窗口包含可供观看者回放和播放的广播时间范围。响应包含 next_delta_token 字段。
为了优化带宽，请存储最新响应中的 next_delta_token 值。

在下一次请求中，将该值作为 delta_token 查询参数发送。服务器仅返回自该令牌生成以来发生更改的元数据。始终发送您收到的最新令牌。请勿尝试解析、修改或构建令牌。如需了解详情，请参阅方法：metadata。

以下示例用于提取广告元数据：

// Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

如果成功，您会收到 PodMetadata 响应。如果您提供 delta_token 参数，则响应仅包含自服务器生成令牌以来服务器添加或更新的广告、广告插播时间和标记。响应还包含新的 next_delta_token 值。如果任何广告插播时间点已过时，响应还会包含一个 obsolete_ad_break_ids 列表，其中列出了要从缓存中移除的广告插播时间点。

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

保存 tags 对象并将更新合并到本地缓存中。如果存在 obsolete_ad_break_ids 参数，请从缓存中移除这些广告插播时间点以及相关联的广告和代码。
使用 polling_frequency 值设置计时器，以定期请求元数据。在每次轮询中，将最新元数据响应中返回的 next_delta_token 值作为 delta_token 查询参数发送。

将直播加载到视频播放器中

从注册响应中获取会话 ID 后，将该 ID 传递给清单处理程序，或构建清单网址以将流加载到视频播放器中。

如需传递会话 ID，请参阅清单操作工具文档。如果您开发清单操纵器，请参阅直播的清单操纵器。

以下示例展示了如何组装清单网址：

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

当播放器准备就绪后，开始播放。

监听广告事件

检查直播的容器格式是否支持定时元数据：

采用传输流 (TS) 容器的 HLS 视频流使用定时 ID3 标记来传送定时元数据。如需了解详情，请参阅关于采用 HTTP Live Streaming (HLS) 的 Common Media Application Format。
DASH 流使用 EventStream 元素在清单中指定事件。
当分段包含用于载荷数据（包括 ID3 标记）的 Event Message (emsg) box 时，DASH 流会使用 InbandEventStream 元素。如需了解详情，请参阅 InbandEventStream。
CMAF 流（包括 DASH 和 HLS）使用包含 ID3 标记的 emsg 箱。

如需从直播中检索 ID3 标记，请参阅视频播放器的指南。如需了解详情，请参阅处理定时元数据指南

如需从 ID3 标记中检索广告事件 ID，请执行以下操作：

按 scheme_id_uri 过滤事件，其中包含 urn:google:dai:2018 或 https://aomedia.org/emsg/ID3。

从 message_data 字段中提取字节数组。

以下示例将 emsg 数据解码为 JSON：

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

按 TXXXgoogle_{ad_event_ID} 格式过滤 ID3 标记：
```
TXXXgoogle_1022389921
```

显示广告事件数据

如需查找 TagSegment 对象，请执行以下操作：

从 Poll ad metadata 中检索广告元数据 tags 对象。tags 对象是 TagSegment 对象的数组。
使用完整的广告事件 ID 查找类型为 progress 的 TagSegment 对象。
使用广告事件 ID 的前 17 个字符查找其他类型的 TagSegment 对象。

由于客户端应用会定期轮询广告元数据，因此视频播放器在视频流中遇到 ID3 标记与相关联的元数据可用之间可能会出现延迟。如果客户端应用在存储的标记中找不到 ID3 标记，请将该标记保留在队列中，并在下一次元数据轮询后重新处理该标记。将标记保留在队列中，直到处理完成。
获得 TagSegment 后，使用 ad_break_id 属性作为键，在广告元数据 ad_breaks 对象中查找 AdBreak 对象。

以下示例用于查找 AdBreak 对象：
```
{
  "type":"mid",
  "duration":15,
  "ads":1
}
```
使用 TagSegment 和 AdBreak 数据可显示广告插播时间点中广告位置的相关信息。例如 Ad 1 of 3。

发送媒体验证 ping

对于每项广告事件（progress 类型除外），发送媒体验证 ping。 Google DAI 会舍弃 progress 事件，频繁发送这些事件可能会影响应用性能。

如需生成广告事件的完整媒体验证网址，请执行以下操作：

从流响应中，将完整的广告事件 ID 附加到 media_verification_url 值。

使用完整网址发出 GET 请求：

// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

如果成功，您会收到代码状态为 202 的响应。否则，您会收到 404 错误代码。

您可以使用视频流活动监控工具 (SAM) 来检查所有广告事件的历史日志。如需了解详情，请参阅监控和排查直播问题