使用 Video Stitcher API,您每次开始播放直播时都会创建一个直播会话,系统会在广告插播期间动态拼接广告。响应中包含播放网址和直播配置 会话。
本页面介绍了如何创建和管理非 由 Google Ad Manager 启用如需详细了解这些类型的直播 会话,请参阅 管理 Google Ad Manager 启用的实时会话。
准备工作
创建实时会话
如需创建实时会话,请使用
projects.locations.liveSessions.create
方法。
在创建直播会话时,以下字段为选填字段:
adTagMacros
:用于广告代码宏替换的键值对列表;请参阅广告代码宏部分manifestOptions
:指定视频呈现方式 拼接视频清单中生成的内容以及呈现顺序; 请参阅清单选项文档
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", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_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
在尝试此示例之前,请按照Java Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 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
在尝试此示例之前,请按照PHP Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 Video Stitcher API PHP API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
在试用此示例之前,请按照 Video Stitcher API 快速入门:使用客户端库中的 Python 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
在尝试此示例之前,请按照Ruby Video Stitcher API 快速入门:使用 客户端库。 有关详情,请参阅 Video Stitcher API Ruby API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
响应为实时会话对象。通过
playUri
是客户端设备用来播放广告拼接流的网址
这场直播中
Video Stitcher API 会为每个请求生成唯一的会话 ID。如果过去 5 分钟内未请求 playUri
,会话将过期。
广告必须先编码,然后才能拼接到实时会话中。为添加了广告的视频创建会话时,Video Stitcher API 会确定广告是否已从上一个会话进行编码。API 只会查找 由与您的 Google Cloud 项目关联的会话创建的编码广告。有关 如需了解此流程,请参阅概览。
如果您要代表客户的设备生成会话,则可以使用 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 不匹配设备(如果会话被
代表客户的设备。
广告代码宏
广告代码可以包含宏,这些宏可为每个广告素材生成不同的广告代码 会话。广告代码中的宏用方括号表示,如以下示例所示:
AD_TAG_URI¯o=[my-key]
adTagUri
在实时配置中定义。
如需替换广告代码宏中的值,请在 adTagMacros
字段中提供映射。例如,如果您想将 [my-key]
宏替换为字符串 my-value
,则需要提供以下内容:
{ ... "adTagMacros": { "my-key": "my-value" }, ... }
当 Video Stitcher API 请求广告元数据时,它会使用以下广告代码:
AD_TAG_URI¯o=my-value
获取会话
如需获取实时会话,请使用 projects.locations.liveSessions.get
方法。
REST
在使用任何请求数据之前,请先进行以下替换:
PROJECT_NUMBER
:您的 Google Cloud 项目 编号,位于 IAM 设置的项目编号字段中 页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", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", }
C#
在尝试此示例之前,请按照C# Video Stitcher API 快速入门:使用 客户端库。 有关详情,请参阅 Video Stitcher API C# API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
在试用此示例之前,请按照 Video Stitcher API 快速入门:使用客户端库中的 Go 设置说明进行操作。 有关详情,请参阅 Video Stitcher API Go API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
在尝试此示例之前,请按照Java Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 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
在尝试此示例之前,请按照Python Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
在尝试此示例之前,请按照Ruby Video Stitcher API 快速入门:使用 客户端库。 有关详情,请参阅 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://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts
处理客户端广告跟踪
启用客户端广告跟踪后,播放器负责触发广告跟踪事件。Video Stitcher API 提供的广告元数据包括广告跟踪和随播广告信息。Video Stitcher API 会解析此 从广告代码响应中提取信息
从清单中获取 HLS 广告元数据 URI
在 HLS 呈现清单中,AdMetadataURI
以属性的形式编码
第 X-VAST-META
个代码(共 #EXT-X-DATERANGE
个代码)。#EXT-X-DATERANGE
代码位于每个广告的第一个接缝片段之前。
以下是 HLS 定时元数据标记的示例:
#EXT-X-DATERANGE:ID="id123",START-DATE=2014-03-05T11:15:00Z,DURATION=15,X-VAST-META="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"
X-VAST-META
属性的值是 base64 编码的 JSON 字符串。更新后
解码后,您可以从 JSON 中提取 AdMetadataURI
。
以下示例展示了经过解码的 X-VAST-META
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
从清单中获取 DASH 广告元数据 URI
在 DASH 清单中,每个拼接广告时段都包含一个 VAST 广告及其广告
元数据 URI 可从 EventStream
标记内提取。AdMetadataURI
是在 Event
元素的 messageData
属性中编码的。Event
是标记 EventStream
内的元素,其 schemeIdUri
为 urn:videostitcher:admetadata:202008
。
以下是 DASH 事件流代码示例:
<EventStream schemeIdUri="urn:videostitcher:admetadata:202008" timescale="1000">
<Event duration="5000" messageData="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"></Event>
</EventStream>
使用 base64 将 messageData
解码为 JSON。
以下示例展示了经过解码的 messageData
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
检索和处理广告跟踪事件
获取 AdMetadataURI
后,您可以提取广告元数据。
以下示例展示了广告元数据:
{
"activityEvents": [
{
"type": "PAUSE",
"uri": "https://example.com/pause"
}
],
"progressiveEvents": [
{
"timeOffset": "0s",
"events": [
{
"type": "IMPRESSION",
"uri": "https://example.com/impression"
},
{
"type": "START",
"uri": "https://example.com/start"
}
]
},
{
"timeOffset": "2.500s",
"events": [
{
"type": "FIRST_QUARTILE",
"uri": "https://example.com/firstquartile"
}
]
}
],
"adDuration": "10s"
}
在前面的示例中,客户端应执行以下操作:
- 在广告视频开始播放时请求
https://example.com/start
- 在广告视频开始播放时请求
https://example.com/impression
- 每当观看者暂停广告视频时请求
https://example.com/pause
- 向广告视频请求
https://example.com/firstQuartile
2.5 秒
检查实时会话
本部分介绍如何检查实时会话和 指定实时会话有关详情,请参阅 REST 文档。
Video Stitcher API 会向实时会话请求正文中的广告代码中指定的广告提供商发送请求。这些请求的请求和响应元数据会保存 14 天,您可以通过检查实时会话来查看这些元数据。
Video Stitcher API 使用以下内容编写广告代码详细信息:
- 给定广告插播时段中请求的广告代码网址(如果未指定,则为默认广告代码)
- 实时会话请求中配置的广告代码宏
- 其他用户元数据
这些信息以及响应的正文和元数据可让您深入了解 Video Stitcher API 的行为。
列出广告代码详情
要列出实时会话的广告代码详情,请使用
projects.locations.liveSessions.liveAdTagDetails.list
方法。
请考虑以下针对之前创建的实时会议的响应(省略了部分字段):
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", ... }
REST
在使用任何请求数据之前,请先进行以下替换:
PROJECT_NUMBER
:您的 Google Cloud 项目 编号,位于 IAM 设置的项目编号字段中 页LOCATION
:会话的位置;使用以下任一 支持的区域显示营业地点us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
:直播会话的标识符
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{ "liveAdTagDetails" : [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] } ] }
复制返回的 LIVE_AD_TAG_DETAILS_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
在尝试此示例之前,请按照PHP Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 Video Stitcher API PHP API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
在尝试此示例之前,请按照Python Video Stitcher API 快速入门:使用 客户端库。 如需了解详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
在试用此示例之前,请按照 Video Stitcher API 快速入门:使用客户端库中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Video Stitcher API Ruby API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
获取广告代码详情
如需获取直播会话中单个广告代码的详细信息,请使用 projects.locations.liveSessions.liveAdTagDetails.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
:实时会话的标识符LIVE_AD_TAG_DETAILS_ID
:实时广告代码详细信息的 ID
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] }
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
在尝试此示例之前,请按照Java Video Stitcher API 快速入门:使用 客户端库。 有关详情,请参阅 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
在尝试此示例之前,请按照Python Video Stitcher API 快速入门:使用 客户端库。 有关详情,请参阅 Video Stitcher API Python API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
在试用此示例之前,请按照 Video Stitcher API 快速入门:使用客户端库中的 Ruby 设置说明进行操作。 有关详情,请参阅 Video Stitcher API Ruby API 参考文档。
如需向 Video Stitcher API 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。