使用 Video Stitcher API,您可以在向客户端设备投放之前,每次动态插入由 Google Ad Manager 投放的广告时,创建一个视频点播 (VOD) 会话。创建会话时,响应会包含播放网址以及您插入视频的广告的相关信息。
本页面介绍了如何创建和管理由 Google Ad Manager 启用的 VOD 会话。如需了解不使用 Google Ad Manager 的 VOD 会话,请参阅管理 VOD 会话。
准备工作
- 创建 VOD 配置。如需与
Google Ad Manager 集成,请确保设置
gamVodConfig对象。
创建会话
您可以使用 IMA SDK(调用 Video Stitcher API)或直接使用 Video Stitcher API 来创建 VOD 会话。
使用 IMA SDK
如果您要与 IMA SDK 集成,则 IMA SDK 会创建 VOD 会话。
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamManager.requestStream(streamRequest); }
由 Google Ad Manager 启用的 VOD 会话必须使用客户端广告跟踪。
您可以为每个会话设置或替换以下可选参数:
manifestOptions:指定在拼接的视频清单中生成的视频版本以及这些版本的顺序;请参阅清单选项文档targetingParameters:Google Ad Manager 广告代码 可以包含 定位参数,这些参数可以按会话更新 ;请参阅 如何使用 IMA SDK 设置定位参数
请参阅下一部分,了解如何使用 IMA SDK 设置这些参数。
可选参数和替换
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.videoStitcherSessionOptions = { manifestOptions: { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" }, ], "bitrateOrder": "descending", }, }; streamRequest.adTagParameters = { "key1": "value1", "key2": "value2", }; streamManager.requestStream(streamRequest); }
直接使用 API
如需为拼接广告的视频创建会话,请使用
projects.locations.vodSessions.create 方法。
REST
在使用任何请求数据之前, 请进行以下替换:
PROJECT_NUMBER:您的 Google Cloud 项目 编号,位于 项目编号 字段中,在 IAM 设置 页面上LOCATION:用于创建会话的位置;请使用其中一个受支持的区域显示位置us-central1us-east1us-west1asia-east1asia-south1asia-southeast1europe-west1southamerica-east1
VOD_CONFIG_ID:用户定义的 VOD 配置标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID",
"interstitials": {
"sessionContent": {
"duration": "60s"
}
},
"playUri": "PLAY_URI", # This is the ad-stitched VOD URI
"sourceUri": "VOD_URI",
"adTagUri": "AD_TAG_URI",
"assetId": "ASSET_ID",
"adTracking": "SERVER",
"vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID"
}
C#
在试用此示例之前,请按照C#设置说明进行操作。请按照 《Video Stitcher API 快速入门:使用客户端库》中的说明进行操作。如需了解详情,请参阅 Video Stitcher API C# API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Go
在试用此示例之前,请按照《Go 设置说明》中的 Video Stitcher API 快速入门:使用 客户端库进行操作。 如需了解详情,请参阅 Video Stitcher API Go API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Java
在试用此示例之前,请按照《Video Stitcher API 快速入门: 使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Java API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Node.js
在试用此示例之前,请按照Node.js设置说明进行操作,这些说明位于《Video Stitcher API 快速入门:使用客户端库》中。如需了解详情,请参阅 Video Stitcher API Node.js API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
PHP
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Video Stitcher API PHP API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Python
在试用此示例之前,请按照《 Video Stitcher API 快速入门:使用 客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Ruby
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Video Stitcher API Ruby API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Video Stitcher API 会为每个请求生成唯一的会话 ID。会话会在 4 小时后过期。
响应现在应类似于以下内容:
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID",
"interstitials": {
"adBreaks": [
{
"progressEvents": [
{
"timeOffset": "0s",
"events": [
{
"type": "IMPRESSION",
"uri": "https://securepubads.g.doubleclick.net/pcs/view..."
},
{
"type": "START",
"uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
},
...
]
},
...
],
"ads": [
{
"duration": "10s",
"activityEvents": [
{
"type": "ERROR",
"uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
},
{
"type": "CLICK_THROUGH",
"uri": "https://pubads.g.doubleclick.net/pcs/click...",
"id": "GDFP"
},
...
]
}
],
"endTimeOffset": "10s",
"startTimeOffset": "0s"
}
],
"sessionContent": {
"duration": "70s"
}
},
"playUri": "PLAY_URI",
"sourceUri": "VOD_URI",
"adTagUri": "AD_TAG_URI",
"assetId": "ASSET_ID",
"adTracking": "SERVER",
"vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID"
}
响应是一个
VodSession 对象
,其中包含以下字段:
- 一个
name字段,用于显示 VOD SESSION_ID。使用此 ID 获取会话。 - 一个
interstitials字段,其中包含有关插入的广告的元数据(请参阅 广告元数据概念)。 - 一个
playUri字段,用于显示客户端设备用于播放条件视频素材资源的网址。
如果您要代表客户的设备生成会话,请使用 HTTP 标头设置以下参数:
| 参数 | HTTP 标头 |
|---|---|
| CLIENT_IP | x-user-ip |
| REFERRER_URL | referer |
| USER_AGENT | user-agent |
您可以将以下标头添加到前面的 curl 请求中:
-H "x-user-ip: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
获取会话
如需获取拼接广告的视频的会话,请使用
projects.locations.vodSessions.get 方法。
REST
在使用任何请求数据之前, 请进行以下替换:
PROJECT_NUMBER:您的 Google Cloud 项目 编号,位于 项目编号 字段中,在 IAM 设置 页面上LOCATION:会话的位置;请使用其中一个 受支持的区域显示位置us-central1us-east1us-west1asia-east1asia-south1asia-southeast1europe-west1southamerica-east1
SESSION_ID:VOD 会话的标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID",
"interstitials": {
"adBreaks": [
{
"progressEvents": [
{
"timeOffset": "0s",
"events": [
{
"type": "IMPRESSION",
"uri": "https://securepubads.g.doubleclick.net/pcs/view..."
},
{
"type": "START",
"uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
},
...
]
},
...
],
"ads": [
{
"duration": "10s",
"activityEvents": [
{
"type": "ERROR",
"uri": "https://pubads.g.doubleclick.net/pagead/interaction/..."
},
{
"type": "CLICK_THROUGH",
"uri": "https://pubads.g.doubleclick.net/pcs/click...",
"id": "GDFP"
},
...
]
}
],
"endTimeOffset": "10s",
"startTimeOffset": "0s"
}
],
"sessionContent": {
"duration": "70s"
}
},
"playUri": "PLAY_URI",
"sourceUri": "VOD_URI",
"adTagUri": "AD_TAG_URI",
"assetId": "ASSET_ID",
"adTracking": "SERVER",
"vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID"
}
C#
在试用此示例之前,请按照C#设置说明进行操作。请按照 《Video Stitcher API 快速入门:使用客户端库》中的说明进行操作。如需了解详情,请参阅 Video Stitcher API C# API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Go
在试用此示例之前,请按照《Go 设置说明》中的 Video Stitcher API 快速入门:使用 客户端库进行操作。 如需了解详情,请参阅 Video Stitcher API Go API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Java
在试用此示例之前,请按照《Video Stitcher API 快速入门: 使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Java API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Node.js
在试用此示例之前,请按照Node.js设置说明进行操作,这些说明位于《Video Stitcher API 快速入门:使用客户端库》中。如需了解详情,请参阅 Video Stitcher API Node.js API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
PHP
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Video Stitcher API PHP API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Python
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
Ruby
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Video Stitcher API Ruby API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅 为本地开发环境设置身份验证。
拼接广告的播放列表示例
以下示例展示了拼接广告之前的源 VOD 播放列表:
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-ENDLIST
以下示例展示了拼接广告之后(包含前贴片广告、中贴片广告和后贴片广告)的源 VOD 播放列表:
#EXTM3U
#EXT-X-VERSION:4
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:0.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-ENDLIST
处理客户端广告跟踪
IMA SDK 会自动处理客户端广告跟踪。
检查由 Google Ad Manager 启用的 VOD 会话
如需检查视频点播会话以及这些会话的广告代码详情,请使用 Ad Manager 中的 “视频流活动监控工具”。