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

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

前提条件

在继续操作之前,您必须满足以下条件:

发出流式传输请求

当用户选择直播时,请执行以下操作:

  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": "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
    }
    
  3. 在 JSON 响应中,找到直播会话 ID 并存储其他数据,以供后续步骤使用。

轮询广告元数据

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

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

  2. 向 metadata_url 端点发出初始 GET 请求。

    • 省略 delta_token 查询参数。通过此过程,服务器可以返回直播的数字视频录像机 (DVR) 时间范围的完整元数据。DVR 时间范围包含观看者可回放和播放的直播时间范围。回答包含 next_delta_token 字段。
  3. 为了优化带宽,请存储最新响应中的 next_delta_token 值。

  4. 在下次请求时,将该值作为 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
        },
        ...
      }
    }
    
  5. 保存 tags 对象,并将更新合并到本地缓存中。如果存在 obsolete_ad_break_ids 参数,请从缓存中移除这些广告插播时间点以及关联的广告和代码。

  6. 使用 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) 的通用媒体应用格式。

  • DASH 视频流使用 EventStream 元素在清单中指定事件。

  • 当分段包含用于载荷数据(包括 ID3 标记)的事件消息 (emsg) 框时,DASH 视频流会使用 InbandEventStream 元素。如需了解详情,请参阅 InbandEventStream。

  • CMAF 流(包括 DASH 和 HLS)使用包含 ID3 标签的 emsg 框。

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

如需从 ID3 标签中检索广告事件 ID,请执行以下操作:

  1. 使用 urn:google:dai:2018 或 https://aomedia.org/emsg/ID3 按 scheme_id_uri 过滤事件。
  2. 从 message_data 字段中提取字节数组。

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

    {
      "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
      "presentation_time": 27554,
      "timescale": 1000,
      "message_data": "ID3TXXXgoogle_1022389921",
      ...
    }
    
  3. 使用以下格式过滤 ID3 标签:TXXXgoogle_{ad_event_ID}

    TXXXgoogle_1022389921
    

显示广告事件数据

如需查找 TagSegment 对象,请执行以下操作:

  1. 从轮询广告元数据中检索广告元数据 tags 对象。tags 对象是 TagSegment 对象数组。

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

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

    由于客户端应用会定期轮询广告元数据,因此在视频播放器遇到视频流中的 ID3 标签与关联元数据可用之间可能会出现延迟。如果您的客户端应用在存储的代码中未找到 ID3 代码,请将该代码保留在队列中,并在下次元数据轮询后重新处理该代码。将代码保留在队列中,直到处理完成。

  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_1022389921`;
    
    const response = await fetch(completeUrl);
    

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

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