准备工作
本文档仅涵盖未采用 IMA DAI SDK。
确保您已完成 将 Google Ad Manager (GAM) 与 VOD 素材资源集成 。
如果 IMA SDK 不适用于您的目标平台，您需要让应用自行调用所需的 API 并触发广告媒体验证。
为此，您需要提供以下信息：
| 位置 |
通过
Google Cloud 区域
：
LOCATION
|
| 项目编号 |
使用视频拼接器的 Google Cloud 项目的编号
API：
PROJECT_NUMBER
|
| OAuth 令牌 |
具有 Video Stitcher 用户角色的服务账号的短期有效 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 |
当前直播会话的到期时间（采用 ISO 8601 标准）
yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 中的日期时间字符串
格式。
|
示例请求 (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 请求。作为回报， 收到包含数据流清单 URI 和元数据的 JSON 响应 例如广告插播时间点、广告和广告事件
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 对象
正文。
|
请求示例 (cURL)
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，媒体 ID 限于 google_ 前缀后的前 10 位数字，因此不存在直接匹配 标记对象中的 ID3 媒体验证 ID 和密钥之间。这是为了 阻止在 ID3 事件之前发送事件验证 ping 。若要生成广告事件的完整媒体验证网址，请执行以下操作： 将完整的广告事件 ID 附加到 流创建响应。
- 使用“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 已发送。 |
请求示例 (cURL)
curl MEDIA_VERIFICATION_URLAD_MEDIA_ID示例响应
HTTP/1.1 204 No Content
限制
如果在网页视图中使用该 API，则在定位方面存在以下限制：
- UserAgent：用户代理参数作为浏览器专用值进行传递 而不是底层平台
- rdid、idtype、is_lat：设备 ID 未正确传递，
会限制以下功能的功能：
- 频次上限
- 依序广告轮播
- 受众群细分和定位