如需为您的项目启用 Video Stitcher API，请与您的客户代表联系，或与销售团队联系以了解详情。

此页面由 Cloud Translation API 翻译。

使用自定义集成

准备工作

本指南仅介绍在未使用 IMA DAI SDK 的情况下的播放说明。

请确保您已先前完成将 Google Ad Manager (GAM) 与直播集成中的步骤。

如果 IMA SDK 不适用于您的目标平台，您需要让应用自行调用所需的 API 并触发广告展示。

为此，您需要提供以下信息：

位置	您创建实时配置的 Google Cloud 区域： `LOCATION`
项目编号	使用 Video Stitcher API 的 Google Cloud 项目的项目编号： `PROJECT_NUMBER`
OAuth 令牌	具有视频拼接工具用户角色的服务账号的短期有效 OAuth 令牌： `OAUTH_TOKEN` 详细了解如何创建短时有效的 OAuth 令牌。要点：只要 OAuth 令牌未过期，就可以在多个请求中重复使用。
广告资源网代码	用于请求广告的 Ad Manager 广告资源网代码： `NETWORK_CODE`
实时配置 ID	您在创建直播活动时指定的实时配置 ID： `LIVE_CONFIG_ID`
自定义素材资源键	使用 Video Stitcher API 为直播活动创建配置过程中生成的 Ad Manager 自定义素材资源键： `CUSTOM_ASSET_KEY`

向 Ad Manager 发出直播注册请求

向串流注册端点发出 POST 请求。作为回报，您会收到一个 JSON 响应，其中包含要发送到视频拼接 API 的串流 ID。

API 端点

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

路径参数

`NETWORK_CODE`	您的 Google Ad Manager 360 广告联盟代码： `NETWORK_CODE`
`CUSTOM_ASSET_KEY`	在 Google Ad Manager 中与此事件关联的自定义标识符： `CUSTOM_ASSET_KEY`

表单编码的正文参数

一组可选的采用表单编码的定位参数。

响应 JSON

`media_verification_url`	用于对播放跟踪事件执行 ping 操作的基础网址。将广告事件 ID 附加到此基本网址即可构成完整的媒体验证网址。 `MEDIA_VERIFICATION_URL`
`metadata_url`	用于请求广告连播元数据的网址。 `METADATA_URL`
`polling_frequency`	轮询 `metadata_url` 的建议频率（以毫秒为单位）。 `POLLING_FREQUENCY`
`stream_id`	用于标识当前串流会话的字符串。 `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 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

示例响应

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

如果发生错误，系统会返回标准 HTTP 错误代码，但不返回 JSON 响应正文。

解析 JSON 响应并存储相关值。

生成会话播放 URI

向视频拼接器 API 的 /livesessions 端点发出 POST 请求，以创建新的直播会话。作为回报，您会收到一个 JSON 响应，其中包含要加载到视频播放器中的直播清单。

API 端点

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

路径参数

`PROJECT_NUMBER`	使用 Video Stitcher API 的 Google Cloud 项目的项目编号： `PROJECT_NUMBER`
`LOCATION`	您创建实时配置的 Google Cloud 区域： `LOCATION`

授权标头参数

OAUTH_TOKEN

具有视频拼接工具用户角色的服务账号的短期有效 OAuth 令牌：

OAUTH_TOKEN

JSON 编码的正文参数

`liveConfig`	一个字符串，其中包含您的项目编号、位置和实时配置 ID，格式如下： `projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID`
`adTracking`	设置为 `"CLIENT"` 可启用客户端跟踪。
`gamSettings`	包含数据流 ID 的对象，格式如下： `{"streamId":"STREAM_ID"}`

响应 JSON

`name`	实时会话的名称，包含会话 ID。
`playUri`	拼接的串流清单的 URI，用于加载到视频播放器中进行播放。 `PLAY_URI`
`liveConfig`	在请求正文中发送给 API 的相同 `liveConfig` 字符串。
`gamSettings`	在请求正文中发送到 API 的相同 `gamSettings` 对象。

请求示例 (c网址)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

示例响应

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

收到响应后，您可以通过引用响应对象的 playUri 字段中的会话播放 URI 来播放广告插播的直播。

Video Stitcher API 会为每个请求生成唯一的会话 ID，您可以从响应对象的 name 字段的最后一部分检索该 ID。

空闲会话会在 5 分钟后过期。如果在一段时间内未提取任何清单，则会话会被视为空闲。

轮询新的广告插播时间点元数据

应用负责检索每个广告插播的元数据，以便知道需要触发哪些展示。为此，您需要设置一个计时器，以便定期轮询 DAI API metadata_url 以获取新的广告信息。轮询间隔在流注册响应的 polling_frequency 字段中指定。

作为回报，您会收到一个包含以下参数的 JSON 对象：

`tags`	一组键值对，用于描述在数据流中发生的广告媒体事件。每个键都由将显示在数据流的 ID3 元数据中的广告媒体 ID 的前 17 个字符组成，对于“进度”事件，则由整个广告媒体 ID 组成。每个值都是一个具有以下属性的对象： `ad`：包含广告媒体事件的广告的 ID。 `ad_break_id`：包含广告媒体事件的广告插播的 ID。 `type`：广告媒体事件的类型。值为以下任一值： `start` - 广告已开始播放 `firstquartile` - 广告已播放 25%。 `midpoint` - 广告播放量达到 50%。 `thirdquartile` - 广告已播放 75%。 `complete` - 广告已结束。 `progress` - 在广告播放期间每秒触发一次。
`ads`	一组键值对，用于描述将在直播中展示的广告。每个键都是一个广告 ID。每个值都是一个具有以下属性的对象： `ad_break_id`：包含广告媒体事件的广告插播的 ID。 `position`：广告在广告插播中的展示位置。请注意，广告插播中的第一个广告的广告位是 `1`。 `duration`：广告时长（以浮点秒为单位）。 `title`：广告的标题（如 VAST 中所定义）。 `description`：广告的说明，如 VAST 中所定义。 `ad_system`：广告系统（如 VAST 中所定义）。 `ad_system`：广告 ID，如 VAST 中所定义。 `ad_system`：广告素材 ID，如 VAST 中所定义。 `clickthrough_url`：用户与广告互动时要打开的网址。 `universal_ad_id`：表示通用广告 ID 的对象，如 VAST 中所定义。
`ad_breaks`	一组键值对，用于描述直播中将出现的广告插播。每个键都是一个广告插播 ID。每个值都是一个具有以下属性的对象： `type`：广告插播的类型。值将是以下值之一： `pre`：表示前贴片广告。 `mid`：表示中贴片广告。 `post`：表示后贴片广告。 `duration`：广告插播时长（以浮点秒为单位）。 `expected_duration`：广告插播的预期时长（以浮点秒为单位）。 `ads`：广告插播中包含的广告数量。

在每次轮询后存储这些值，以便在视频串中关联定时元数据事件。

请求示例 (c网址)

curl https://dai.google.com/.../metadata/

示例响应

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },
      ...
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/...",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },
      ...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },
      ...
   }
}

监听 ID3 事件并跟踪播放事件

如需验证视频串流中是否发生了特定事件，请按照以下步骤处理 ID3 事件：

将媒体事件存储在队列中，并保存每个媒体 ID 及其时间戳（如果由播放器显示）。
在播放器每次更新时或以设定的频率（建议为 500 毫秒）检查媒体事件队列，方法是将事件时间戳与播放头进行比较，以查看最近播放的事件。
对于您确认已播放的媒体事件，请在存储的广告插播代码中查找媒体 ID，以检查其类型。请注意，广告插播代码对象仅包含经过截断的媒体 ID，仅限于 google_ 前缀后的前 10 位数字，因此 ID3 媒体验证 ID 与代码对象中的键之间没有直接匹配。这是为了防止在 ID3 事件到达之前发送事件验证 ping。如需生成广告事件的完整媒体验证网址，请将完整的广告事件 ID 附加到数据流创建响应的 media_verification_url 值。
使用“progress”（进度）事件跟踪用户是否处于广告插播期间。请勿将这些事件发送到媒体验证端点，以免出现 HTTP 错误代码。对于其他事件类型，请将媒体 ID 附加到媒体验证网址，然后发出 GET 请求以跟踪播放。
从队列中移除媒体事件。

API 端点

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

路径参数

`MEDIA_VERIFICATION_URL`	串流注册端点返回的值（在 `media_verification_url` 字段中）： `MEDIA_VERIFICATION_URL`
`AD_MEDIA_ID`	广告媒体的完整 ID（如在数据流的 ID3 元数据中显示）： `AD_MEDIA_ID`

预期返回值

`HTTP/1.1 204 No Content`	成功的空响应。
`HTTP/1.1 404 Not Found`	系统无法识别媒体验证 ID。
`HTTP/1.1 409 Conflict`	媒体验证 ID 已发送。

请求示例 (c网址)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

示例响应

HTTP/1.1 204 No Content

限制

如果在网页视图中使用该 API，则在定位方面存在以下限制：

UserAgent：用户代理参数作为浏览器专用值（而非底层平台）传递。
rdid、idtype、is_lat：未正确传递设备 ID，这会限制以下功能的功能：
- 频次上限
- 依序轮播广告
- 受众群细分和定位

tvOS

清理