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

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

前提条件

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

• 配置为 Pod serving redirect DAI 类型的直播活动的自定义素材资源键。如需获取此密钥，请执行以下操作：

  • 设置 DAI 直播。

  • 使用 SOAP API 客户端库调用 LiveStreamEventService.createLiveStreamEvents 方法，并使用 LiveStreamEvent 对象和设置为 POD_SERVING_REDIRECT 枚举值的 dynamicAdInsertionType 属性。如需查看所有客户端库，请参阅客户端库和示例代码。

• 确定互动式媒体广告 (IMA) SDK 是否适用于您的平台。我们建议使用 IMA SDK 来提高收入。如需了解详情，请参阅为 DAI 设置 IMA SDK。

发出流式请求

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

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

2. 以 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": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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
   }
   

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

轮询广告元数据

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

1. 从流注册响应中读取 metadata_url 值。

2. 向端点发出 GET 请求。如需了解详情，请参阅方法：元数据。

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

   const response = await fetch(metadata_url);
   console.log(await response.json());
   

   如果成功，您将收到当前和即将到来的广告插播时间的 PodMetadata 响应：

   {
     "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
       },
       ...
     }
   }
   

3. 保存 tags 对象以供后续步骤使用。

4. 使用 polling_frequency 值设置计时器，以便定期请求所有后续广告插播的元数据。

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

从注册响应中获取会话 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 box。

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

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

1. 按 scheme_id_uri 过滤事件，使用 urn:google:dai:2018 或 https://aomedia.org/emsg/ID3。

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

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

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

3. 过滤格式为 TXXXgoogle_{ad_event_ID} 的 ID3 标记：

   TXXXgoogle_1234567890123456789
   

显示广告事件数据

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

1. 从 Poll ad metadata 中检索广告元数据 tags 对象。tags 对象是 TagSegment 对象的数组。

2. 使用完整的广告事件 ID 查找类型为 progress 的 TagSegment 对象。

3. 使用广告事件 ID 的前 17 个字符查找其他类型的 TagSegment 对象。

4. 获得 TagSegment 后，使用 ad_break_id 属性作为键，在广告元数据 ad_breaks 对象中查找 AdBreak 对象。

   以下示例用于查找 AdBreak 对象：

   {
     "type":"mid",
     "duration":15,
     "ads":1
   }
   

5. 使用 TagSegment 和 AdBreak 数据来显示广告插播时间点中广告位置的相关信息。例如 Ad 1 of 3。

发送媒体验证 ping

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

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

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

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

   // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
   const completeUrl = `${media_verification_url}google_5555555555123456789`;
   
   const response = await fetch(completeUrl);
   

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

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