准备工作
本文档仅介绍未使用 IMA DAI SDK 时的播放说明。
请确保您已事先完成将 Google Ad Manager (GAM) 与 VOD 资产集成中的步骤。
如果 IMA SDK 不适用于您的目标平台，您需要让应用自行调用所需的 API 并触发广告媒体验证。
为此，您需要提供以下信息：
| 位置 |
您创建实时配置的
Google Cloud 区域
：LOCATION
|
| 项目编号 |
使用 Video Stitcher API 的 Google Cloud 项目的项目编号：PROJECT_NUMBER
|
| OAuth 令牌 |
具有视频拼接工具用户角色的服务账号的短期有效 OAuth 令牌：OAUTH_TOKEN 详细了解如何 创建短时有效的 OAuth 令牌。 |
| 广告资源网代码 |
用于请求广告的 Ad Manager 广告资源网代码：NETWORK_CODE |
| VOD 配置 ID |
您在创建 VOD 串流事件时指定的 VOD 配置 ID：VOD_CONFIG_ID |
向 Ad Manager 发出数据流注册请求
向串流注册端点发出 POST 请求。作为回报，您会收到一个 JSON 响应，其中包含要发送到清单处理服务器和关联的 Pod Serving API 端点的串流 ID。
API 端点
POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json
路径参数
NETWORK_CODE |
您的 Google Ad Manager 360 广告资源网代码 |
JSON 编码的正文参数
targeting_parameters- 一组可选的 JSON 编码定位参数。
响应 JSON
media_verification_url |
用于对播放跟踪事件执行 ping 操作的基础网址。将广告事件 ID 附加到此基本网址即可构成完整的媒体验证网址。
MEDIA_VERIFICATION_URL
|
metadata_url |
用于请求广告连播元数据的网址。
METADATA_URL
|
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/json" \
-d '@request.json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registrationrequest.json
{
"targeting_parameters": {
"cust_params": "sport%3Dfootball%26city%3Dnewyork"
}
}
示例响应
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
如果发生错误，系统会返回标准 HTTP 错误代码，但不返回 JSON 响应正文。
解析 JSON 响应并存储相关值。
生成 Cloud Video Stitcher VOD 会话
向 VOD 会话注册端点发出 POST 请求。作为回报，您会收到一个 JSON 响应，其中包含直播清单 URI 以及与广告插播时间点、广告和广告事件相关的元数据。
API 端点
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
路径参数
PROJECT_NUMBER |
您的 Google Cloud 项目编号。 |
LOCATION |
您的 Google Cloud 区域。 |
NETWORK CODE |
您的 Google Ad Manager 360 广告资源网代码。 |
JSON 编码的正文参数
vodConfig |
一个字符串，其中包含您的项目编号、位置和 VOD 配置 ID，格式如下：
projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
|
adTracking |
设置为 "CLIENT" 可启用客户端跟踪。 |
gamSettings |
一个包含影音平台代码和直播 ID 的对象，格式如下：{ "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" } |
响应 JSON
name |
VOD 会话的名称，包含会话 ID。 |
playUri |
拼接的串流清单的 URI，用于加载到视频播放器中进行播放。
SESSION_PLAYBACK_URI
|
adTracking |
与请求正文中发送给 API 的 adTracking 值相同。
|
vodConfig |
与请求正文中发送给 API 的 vodConfig 字符串相同。
|
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/vodSessions/request.json
{
"vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
"ad_tracking": "CLIENT",
"gam_settings": {
"network_code": "NETWORK_CODE",
"stream_id": "STREAM_ID"
}
}
示例响应
{
"name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
"playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
"sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
"adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
"vodConfig": "projects/...",
"assetId": "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
"adTracking": "CLIENT",
"gam_settings": {
"network_code": "21775744923",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
}
}
收到响应后，您可以通过引用响应对象的 playUri 字段中的 URI 来播放广告插播直播。
从 Ad Manager 请求广告连播元数据
向您在向 Ad Manager 注册数据流时收到的 metadata_url 发出 GET 请求。此步骤必须在您从播放 URI 收到拼接后的清单后执行。
您会收到一个 JSON 对象，其中描述了直播的广告插播时间点、广告和广告事件。
API 端点
GET: METADATA_URL
Host: dai.google.com
响应 JSON
tags |
一组键值对，用于描述在数据流中发生的广告媒体事件。每个键都由将显示在数据流的 ID3 元数据中的广告媒体 ID 的前 17 个字符组成，对于“进度”事件，则由整个广告媒体 ID 组成。每个值都是一个具有以下属性的对象：
|
ads |
一组键值对，用于描述将在直播中展示的广告。每个键都是一个广告 ID。每个值都是一个具有以下属性的对象：
|
ad_breaks |
一组键值对，用于描述直播中将出现的广告插播。每个键都是一个广告插播 ID。每个值都是一个具有以下属性的对象：
|
请求示例 (c网址)
curl METADATA_URLJSON 响应示例
{
"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
},
...
}
}
存储这些值，以便与视频串流中的定时元数据事件相关联。
监听 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，这会限制以下功能的功能：
- 频次上限
- 依序轮播广告
- 受众群细分和定位