借助 Google DAI Pod Serving API,您可以执行由 Google Ads 提供支持的服务器端广告插播,同时保持对自己视频拼接的控制。
本指南介绍了如何与 Pod Serving API 交互以及如何使用 IMA DAI SDK 实现类似功能。有关受支持功能的具体问题,请与您的 Google 客户经理联系。
Pod Serving API 支持采用 HLS 或 MPEG-DASH 流式传输协议的 Pod 传送数据流。本指南重点介绍 HLS 流并在特定步骤中重点介绍 HLS 和 MPEG-DASH 之间的主要区别。
如需将 Pod Serving API 集成到您的应用以用于 VOD 视频流,请完成以下步骤:
向 Ad Manager 发送视频流注册请求
向数据流注册端点发出 POST 请求。反过来,您会收到一个包含数据流 ID 的 JSON 响应,该 ID 将发送到您的清单操纵服务器和关联的 Pod Serving API 端点。
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 对象,包含内容来源 ID (cmsid)、视频 ID (vid) 和广告定位参数。必需 |
响应 JSON
media_verification_url |
用于 ping 播放跟踪事件的基础网址。将广告事件 ID 附加到此基准网址即可形成完整的媒体验证网址。 |
metadata_url |
用于请求广告连播元数据的网址。 |
stream_id |
用于标识当前直播会话的字符串。 |
valid_for |
距离当前流式会话到期的剩余时间,采用 dhms (天、小时、分钟、秒)格式。例如,2h0m0.000s 表示时长为 2 小时。
|
valid_until |
当前流式会话的到期时间,采用 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 格式的 ISO 8601 日期时间字符串。
|
示例请求 (c网址)
curl -X POST \
-d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration
示例响应
{
"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 响应并存储相关值。
从清单操纵器请求数据流清单
每个清单操纵器都有不同的请求和响应格式。请与您的操纵器提供商联系,了解其具体要求。如果您要实现自己的清单操纵器,请参阅清单操纵器指南,了解此组件的要求。
一般来说,您需要将上述注册端点返回的数据流 ID 传递给清单操纵器,以便它构建会话专用清单。除非清单操纵器明确说明,否则对清单请求的响应将是一个同时包含内容和广告的视频流。
示例请求 (c网址)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
示例响应 (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
播放直播
将您从清单操纵服务器收到的清单加载到视频播放器中,然后开始播放。
向 Ad Manager 请求广告连播元数据
向您在第 1 步中收到的 metadata_url
发出 GET
请求。此步骤必须在您从清单操纵器收到拼接后的清单后执行。反过来,您会收到包含以下参数的 JSON 对象:
tags |
一组键值对,其中包含数据流中显示的所有广告事件。键为在数据流的定时元数据中显示的广告事件 ID 的前 17 个字符;如果是 progress 类型的事件,则为完整的广告事件 ID。每个值都是包含以下参数的对象:
|
||||||||||||||||||
ads |
一组键值对,用于描述视频流中显示的所有广告。键是与上面列出的 tags 对象中的值匹配的广告 ID。每个值都是包含以下参数的对象:
|
||||||||||||||||||
ad_breaks |
一组键值对,用于描述视频流中出现的所有广告插播时间点。键是与上面列出的 tags 和 ads 对象中的值匹配的广告插播时间点 ID。每个值都是包含以下参数的对象:
|
存储这些值,以与视频流中的定时元数据事件相关联。
示例请求 (c网址)
curl https://dai.google.com/.../metadata
示例响应
{
"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
},
...
}
}
监听广告事件
通过视频播放器的音频/视频流中触发的广告事件监听定时元数据。
对于 MPEG-TS 流,元数据显示为带内 ID3 v2.3 标记。每个元数据标记都具有 ID TXXX
,其值以字符串 google_
开头,后跟一系列字符。此值就是广告事件 ID。
TXXX
中的 XXX
不是占位符。字符串 TXXX
是为“用户定义的文本”预留的 ID3 代码 ID。
ID3 代码示例
TXXXgoogle_1234567890123456789
对于 MP4 视频流,这些事件会作为模拟 ID3 v2.3 代码的带内 emsg 事件发送。每个相关的 emsgbox 均有一个 scheme_id_uri
值 https://aomedia.org/emsg/ID3
或 https://developer.apple.com/streaming/emsg-id3
,以及一个以 ID3TXXXgoogle_
开头的 message_data
值。这个 message_data
值(不带 ID3TXXX
前缀)是广告事件 ID。
emsg 框示例
数据结构可能会因媒体播放器库而异。
如果广告事件 ID 为 google_1234567890123456789
,响应将如下所示:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
某些媒体播放器库会自动呈现将 ID3 代码模拟为原生 ID3 代码的 emsg 事件。在这种情况下,MP4 流提供与 MPEG_TS 相同的 ID3 标记。
更新客户端视频播放器应用的界面
每个广告事件 ID 都可以与第 4 步中的 tags
对象中的一个键相匹配。匹配这些值的过程分为两个步骤:
检查
tags
对象中是否有与完整广告事件 ID 匹配的键。如果找到匹配项,则检索事件类型及其关联的ad
和ad_break
对象。这些事件的类型为progress
。如果未找到与完整广告事件 ID 的匹配项,请检查
tags
对象中是否有与该广告事件 ID 的前 17 个字符匹配的键。检索事件类型以及关联的ad
和ad_break
对象。这应该会检索progress
以外的类型的所有事件。使用检索到的信息来更新播放器的界面。例如,当您收到
start
或第一个progress
事件时,请隐藏播放器的进度滑块控件,并显示一个叠加层来说明当前广告在广告插播时间点中的位置,例如:“广告 1/3”。
广告事件 ID 示例
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
代码对象示例
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
发送媒体验证 ping
每次收到类型不是 progress
的广告事件时,都必须向 Ad Manager 发送媒体验证 ping。
如需生成广告事件的完整媒体验证网址,请将完整的广告事件 ID 附加到数据流注册响应中的 media_verification_url
值。
使用完整网址发出 GET 请求。如果验证请求成功,您会收到状态代码为 202
的 HTTP 响应。否则,您会收到 HTTP 错误代码 404
。
示例请求 (c网址)
curl https://{...}/media/google_5555555555123456789
成功响应示例
HTTP/1.1 202 Accepted