使用 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
:IAM 设置页面上项目编号字段中显示的 Google Cloud 项目编号LOCATION
:用于创建会话的位置;请使用某个受支持的地区显示位置us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
VOD_CONFIG_ID
:用户定义的视频点播配置标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 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#
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API C# API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Go API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Java API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 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
:IAM 设置页面上项目编号字段中显示的 Google Cloud 项目编号LOCATION
:会话的位置;请使用某个受支持的地区显示位置us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
:视频点播会话的标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 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#
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API C# API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Go API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Java API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
在试用此示例之前,请按照《Video Stitcher API 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 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 会话
如需检查 VOD 会话以及这些会话的广告代码详情,请使用 Ad Manager 中的视频流活动监控器。