如需为您的项目启用 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 令牌	具有 Video Stitcher 用户角色的服务账号的短期有效 OAuth 令牌： `OAUTH_TOKEN` 详细了解创建短期有效的 OAuth 令牌。要点：只要 OAuth 令牌未过期，就可以在多个请求中重复使用。
广告资源网代码	用于请求广告的 Ad Manager 广告资源网代码： `NETWORK_CODE`
实时配置 ID	您在创建直播活动时指定的直播配置 ID： `LIVE_CONFIG_ID`
自定义素材资源键	在创建过程中生成的 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`	当前直播会话的到期时间（采用 ISO 8601 标准） `yyyy-MM-dd'T'hh:mm:ss.sssssssss[+\|-]hh:mm` 中的日期时间字符串格式。

请求示例 (cURL)

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 请求，创建新的直播会话反过来，您会收到一个包含将视频流清单加载到您的视频播放器

API 端点

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

路径参数

`PROJECT_NUMBER`	使用视频拼接器的 Google Cloud 项目的编号 API： `PROJECT_NUMBER`
`LOCATION`	通过 Google Cloud 区域： `LOCATION`

授权标头参数

OAUTH_TOKEN

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

OAUTH_TOKEN

JSON 编码的正文参数

`liveConfig`	包含项目编号的字符串； location 以及 live config 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`：VAST 中定义的广告 ID。 `ad_system`：广告素材 ID，如 VAST 中所定义。 `clickthrough_url`：当用户进行互动时打开的网址。 `universal_ad_id`：表示通用型广告 ID，如 VAST 中所定义。
`ad_breaks`	一组键值对，用于描述直播中将出现的广告插播。每个键都是一个广告插播 ID。每个值都是一个具有以下属性的对象： `type`：广告插播时间点的类型。值将是以下值之一： `pre`：表示前贴片广告。 `mid`：表示中贴片广告。 `post`：表示后贴片广告。 `duration`：广告插播时长（以浮点秒为单位）。 `expected_duration`：广告的预计时长以浮点秒数表示的停顿。 `ads`：广告插播中包含的广告数量。

在每次轮询后存储这些值，以便在您的视频流。

请求示例 (cURL)

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，媒体 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

限制

如果在 WebView 中使用该 API，则对于改为：

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

tvOS

清理