使用 Video Stitcher API,您可以在每次开始播放直播时创建一个直播会话,在广告插播期间,Google Ad Manager 投放的广告会动态拼接。响应包含播放网址和直播会话的配置。
本页介绍了如何创建和管理由 Google Ad Manager 启用的直播会话。如需了解不使用 Google Ad Manager 的直播会话,请参阅管理直播会话。
准备工作
- 创建直播配置。对于与 Google Ad Manager 的集成,请确保已设置
gamLiveConfig
对象。 - 如果您要指定板块,请确保在注册的板块上设置了
gamSlate
对象。
创建实时会话
您可以使用 IMA SDK(它会调用 Video Stitcher API)或直接使用 Video Stitcher API 来创建直播会话。
使用 IMA SDK
如果您是与 IMA SDK 集成,则 IMA SDK 会创建直播会话。
function requestVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest(); streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY'; streamManager.requestStream(streamRequest); }
您可以为每个会话设置或替换以下可选参数:
manifestOptions
:指定在拼接视频清单中生成哪些视频转码版本以及这些转码版本的顺序;请参阅清单选项文档adTracking
:选择客户端广告跟踪或服务器端广告跟踪targetingParameters
:Google Ad Manager 广告代码可以包含可在每个会话中更新的定位参数;请参阅如何使用 IMA SDK 设置定位参数
请参阅下一部分,了解如何使用 IMA SDK 设置这些参数。
可选参数和替换项
您可以为每个会话设置可选参数,例如 manifestOptions
字段。此字段在实时配置中不可用。您还可以替换给定会话的实时配置中设置的某些参数。
例如,如果实时配置中的默认 adTracking
设置为 SERVER
,您可以将该值替换为 CLIENT
,还可以通过设置 videoStitcherSessionOptions
JSON 对象字段来设置 IMA SDK 中的 manifestOptions
字段。
function requestVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest(); streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY'; streamRequest.videoStitcherSessionOptions = { adTracking: 'CLIENT', '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
如需使用 API 直接创建直播会话,请使用 projects.locations.liveSessions.create
方法。
liveConfig
字段是 JSON 正文中唯一的必填字段。您可以为每个直播会话设置或替换以下可选参数(如以下 REST 示例所示):
manifestOptions
:指定在拼接视频清单中生成哪些视频转码版本以及这些转码版本的顺序;请参阅清单选项文档adTracking
:选择客户端广告跟踪或服务器端广告跟踪;此值会替换实时配置中的值(针对相应会话)targetingParameters
:Google Ad Manager 广告代码可以包含可按会话更新的定位参数;在此字段中提供映射(例如,将[my_key]
宏替换为字符串my_value
,请参阅 REST 示例)
REST
在使用任何请求数据之前,请先进行以下替换:
PROJECT_NUMBER
:IAM 设置页面上项目编号字段中显示的 Google Cloud 项目编号LOCATION
:用于创建会话的位置;请使用某个受支持的地区显示位置us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
LIVE_CONFIG_ID
:实时配置的用户定义标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", "playUri": "PLAY_URI", "manifestOptions": { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" } ], "bitrateOrder": "DESCENDING" }, "gamSettings": { "streamId": "STREAM_ID" }, "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", "adTracking": "SERVER" }
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 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
响应是一个实时会话对象。playUri
是客户端设备用于播放相应直播会话的拼接广告视频流的网址。
Video Stitcher API 会为每个请求生成唯一的会话 ID。如果过去 5 分钟内未请求 playUri
,会话就会过期。
如果您要代表客户的设备生成会话,可以使用 HTTP 标头设置以下参数:
参数 | HTTP 标头 |
---|---|
CLIENT_IP | x-forwarded-for |
REFERRER_URL | referer |
USER_AGENT | user-agent |
您可以向上述 curl
请求添加以下标头:
-H "x-forwarded-for: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
如果未提供 x-forwarded-for
标头,Video Stitcher API 会在广告元数据请求中使用客户端的 IP 地址。请注意,如果会话是代表客户的设备生成的,那么客户端的 IP 地址可能与客户设备的 IP 地址不一致。
获取会话
如需获取直播会话,请使用 projects.locations.liveSessions.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/liveSessions/SESSION_ID", "playUri": "ad-stitched-live-stream-uri", "manifestOptions": { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" } ], "bitrateOrder": "DESCENDING" }, "gamSettings": { "streamId": "STREAM_ID", "targetingParameters": { "my_key": "my_value" } }, "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", "adTracking": "SERVER" }
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 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
示例插播广告的播放列表
以下显示了广告拼接之前的示例源直播播放列表:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:32:00Z",DURATION=60,SCTE35-OUT=0xF...
#EXTINF:10.010
segment_00007.ts
#EXTINF:10.010
segment_00008.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:39:20Z",SCTE35-IN=0xF...
#EXTINF:10.010
segment_00009.ts
以下示例展示了广告拼接后的源直播播放列表:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://dai.google.com/.../ad-1/seg-1.ts
#EXTINF:5.000
https://dai.google.com/.../ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://dai.google.com/.../ad-2/seg-1.ts
#EXTINF:5.000
https://dai.google.com/.../ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts
检查由 Google Ad Manager 启用的实时会话
如需查看会话的广告代码详情,请使用 Ad Manager 中的视频流活动监控工具查看广告请求的详情。