借助 Dynamic Ad Placement API,您可以请求和跟踪 DAI 视频点播 (VOD) 视频流。支持 HLS 和 DASH 视频流。
服务:dai.google.com
stream
方法的路径相对于 https://dai.google.com
方法:stream
方法 | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
为指定的内容来源和视频 ID 创建 HLS DAI 视频流。
为指定的内容来源和视频 ID 创建 DASH DAI 视频流。 |
HTTP 请求
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
请求标头
参数 | |
---|---|
api‑key |
string 创建视频流时提供的 API 密钥必须对发布商的广告资源网有效。 您可以在 HTTP Authorization 标头中通过以下格式传递 API 密钥,而不是在请求正文中提供该密钥: Authorization: DCLKDAI key="<api-key>" |
路径参数
参数 | |
---|---|
content-source |
string 视频流的 CMS ID。 |
video-id |
string 视频流的视频 ID。 |
请求正文
请求正文的类型为 application/x-www-form-urlencoded
,包含以下参数:
参数 | ||
---|---|---|
dai-ssb |
可选 | 设置为 |
DFP 定位参数 | 可选 | 其他定位参数。 |
替换视频流参数 | 可选 | 替换数据流创建参数的默认值。 |
HMAC 身份验证 | 可选 | 使用基于 HMAC 的令牌进行身份验证。 |
响应正文
如果成功,响应正文将包含一个新的 Stream
。对于服务器端信标数据流,此 Stream
仅包含 stream_id
和 stream_manifest
字段。
开放式衡量
Verifications
字段包含针对非服务器端信标数据流的 Open Measurement 验证信息。Verifications
包含一个或多个 Verification
元素,其中列出了使用第三方衡量代码验证广告素材播放所需的资源和元数据。系统仅支持 JavaScriptResource
。如需了解详情,请参阅 IAB Tech Lab 和 VAST 4.1 规范。
方法:媒体验证
在播放过程中遇到广告媒体标识符后,立即使用 media_verification_url
从 stream
端点发出请求。media_verification_url
是绝对路径。
对于由服务器启动媒体验证的服务器端信标流,不需要媒体验证请求。
对 media verification
端点的请求具有幂等性。
方法 | |
---|---|
media verification |
GET {media_verification_url}/{ad_media_id}
向 API 发出媒体验证事件通知。 |
HTTP 请求
GET {media-verification-url}/{ad-media-id}
响应正文
media verification
会返回以下响应:
- 如果媒体验证成功且所有 ping 均已发送,则为
HTTP/1.1 204 No Content
。 - 如果因网址格式不正确或已过期而导致请求无法验证媒体,则为
HTTP/1.1 404 Not Found
; - 如果之前对此 ID 的验证请求成功,则为
HTTP/1.1 404 Not Found
。 - 如果此时另一个请求已在发送 ping,则为
HTTP/1.1 409 Conflict
。
广告媒体 ID (HLS)
广告媒体标识符将使用键 TXXX
以 HLS 定时元数据编码,该键为“用户定义的文本信息”帧预留。帧的内容将不会加密,并且始终以文本 "google_"
开头。
对于每个广告验证请求,帧的完整文字内容应附加到 media_verification_url。
广告媒体 ID (DASH)
系统会使用 DASH 的 EventStream
元素将广告媒体标识符插入到清单中。
每个 EventStream
的协议 ID URI 为 urn:google:dai:2018
。它们将包含具有 messageData
属性(包含以 “google_”
开头的广告媒体 ID)的事件。对于每个广告验证请求,messageData
属性的全部内容都应附加到 media_verification_url。
响应数据
直播
数据流用于以 JSON 格式呈现新创建的数据流的所有资源列表。JSON 表示法 |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
字段 | |
---|---|
stream_id |
string 数据流标识符。 |
total_duration |
number 直播时长(秒)。 |
content_duration |
number 内容(不含广告)的时长(以秒为单位)。 |
valid_for |
string 时长视频流的有效期为“00h00m00s”格式。 |
valid_until |
string 数据流的有效期至日期,采用 RFC 3339 格式。 |
subtitles |
[object(Subtitle)] 字幕列表。如果为空,则省略。仅限 HLS。 |
hls_master_playlist |
string (已弃用)HLS 主播放列表网址。使用 stream_manifest。仅限 HLS。 |
stream_manifest |
string 数据流的清单。对应于 HLS 中的主播放列表和 DASH 中的 MPD。 创建服务器端信标流时,这是响应中除“stream_id”之外的唯一字段。 |
media_verification_url |
string 媒体验证网址。 |
apple_tv |
object(AppleTV) 特定于 AppleTV 设备的可选信息。仅限 HLS。 |
ad_breaks |
[object(AdBreak)] 广告插播时间点列表。如果为空,则省略。 |
AppleTV
AppleTV 包含特定于 Apple TV 设备的信息。JSON 表示法 |
---|
{ "interstitials_url": string, } |
字段 | |
---|---|
interstitials_url |
string 插页式广告网址。 |
AdBreak
AdBreak 描述视频流中的单个广告插播时间点。它包含位置、时长、类型(中间/前/后)和广告列表。JSON 表示法 |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
字段 | |
---|---|
type |
string 有效的插播时间点类型包括:mid、pre 和 post。 |
start |
number 广告插播时间点在信息流中的位置(以秒为单位)。 |
duration |
number 广告插播时长(以秒为单位)。 |
ads |
[object(Ad)] 广告列表。如果为空,则省略。 |
Ad
广告描述的是视频流中的广告。它包含广告在广告插播时间点的位置、广告的时长以及一些可选的元数据。JSON 表示法 |
---|
{ "seq": number, "start": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
字段 | |
---|---|
seq |
number 广告在广告插播时间点的位置。 |
start |
number 广告在视频流中开始播放的位置(以秒为单位)。 |
duration |
number 广告的持续时间(以秒为单位)。 |
title |
string 广告的可选标题。 |
description |
string 广告的可选说明。 |
advertiser |
string 可选的广告客户标识符。 |
ad_system |
string 可选广告系统。 |
ad_id |
string 可选的广告 ID。 |
creative_id |
string 可选的广告素材 ID。 |
creative_ad_id |
string 可选的广告素材广告 ID。 |
deal_id |
string 可选交易 ID。 |
clickthrough_url |
string 可选点击后到达网址。 |
icons |
[object(Icon)] 图标列表,为空时省略。 |
wrappers |
[object(Wrapper)] 封装容器列表。如果为空,则省略。 |
events |
[object(Event)] 广告中的事件列表。 |
verifications |
[object(Verification)] 可选的 Open Measurement 验证条目,其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。 |
universal_ad_id |
object(UniversalAdID) 可选的通用广告 ID。 |
companions |
[object(Companion)] 可与此广告一起展示的可选随播广告素材。 |
interactive_file |
object(InteractiveFile) 可选的互动广告素材 (SIMID),应在广告播放期间展示。 |
事件
事件包含事件类型以及事件的呈现时间。JSON 表示法 |
---|
{ "time": number, "type": string, } |
字段 | |
---|---|
time |
number 此活动的展示时间。 |
type |
string 此活动的类型。 |
副标题
字幕用于描述视频流的辅助信息文件字幕轨道。它会存储两种字幕格式:TTML 和 WebVTT。TTMLPath 属性包含 TTML 辅助信息文件的网址,而 WebVTTPath 属性同样包含指向 WebVTT 辅助信息文件的网址。JSON 表示法 |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
字段 | |
---|---|
language |
string 语言代码,例如“en”或“de”。 |
language_name |
string 语言的描述性名称。如果同一语言有多套字幕,它就能区分这组特定的字幕 |
ttml |
string TTML Sidecar 文件的可选网址。 |
webvtt |
string WebVTT 辅助信息文件(可选)的网址。 |
Icon
图标包含有关 VAST 图标的信息。JSON 表示法 |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
字段 | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
ClickData 包含图标点击的相关信息。JSON 表示法 |
---|
{ "url": string, } |
字段 | |
---|---|
url |
string |
FallbackImage
FallbackImage 包含有关 VAST 后备图片的信息。JSON 表示法 |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
字段 | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
Wrapper
封装容器包含封装容器广告的相关信息。但不包含交易 ID(如果不存在)。JSON 表示法 |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
字段 | |
---|---|
system |
string 广告系统标识符。 |
ad_id |
string 用于封装容器广告的广告 ID。 |
creative_id |
string 用于封装容器广告的广告素材 ID。 |
creative_ad_id |
string 用于封装容器广告的广告素材广告 ID。 |
deal_id |
string 封装容器广告的可选交易 ID。 |
验证
Verification 包含 Open Measurement 信息,这有助于第三方可见度和验证衡量。目前仅支持 JavaScript 资源。请参阅 https://iabtechlab.com/standards/open-measurement-sdk/JSON 表示法 |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
字段 | |
---|---|
vendor |
string 验证供应商。 |
java_script_resources |
[object(JavaScriptResource)] 用于验证的 JavaScript 资源列表。 |
tracking_events |
[object(TrackingEvent)] 用于验证的跟踪事件列表。 |
parameters |
string 传递给引导验证码的不透明字符串。 |
JavaScriptResource
JavaScriptResource 包含通过 JavaScript 进行验证的信息。JSON 表示法 |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
字段 | |
---|---|
script_url |
string JavaScript 载荷的 URI。 |
api_framework |
string APIFramework 是执行验证码的视频框架的名称。 |
browser_optional |
boolean 此脚本能否在浏览器外部运行。 |
TrackingEvent
TrackingEvent 包含在某些情况下应由客户端执行 ping 操作的网址。JSON 表示法 |
---|
{ "event": string, "uri": string, } |
字段 | |
---|---|
event |
string 跟踪事件类型,目前唯一的选项是 VAST 4.1 规范中指定的“verificationNotExecuted”。 |
uri |
string 要 ping 的跟踪事件。 |
UniversalAdID
UniversalAdID 用于提供独一无二的广告素材标识符,该标识符可在各个广告系统中维护。JSON 表示法 |
---|
{ "id_value": string, "id_registry": string, } |
字段 | |
---|---|
id_value |
string 为广告选择的广告素材的通用广告 ID。 |
id_registry |
string 一个字符串,用于标识对所选广告素材的通用广告 ID 进行目录编制的注册网站的网址。 |
随播广告
随播广告包含可与广告一起展示的随播广告的信息。JSON 表示法 |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, } |
字段 | |
---|---|
click_data |
object(ClickData) 此随播广告素材的点击数据。 |
creative_type |
string 如果是静态类型的随播广告,则 VAST 中 <StaticResource> 节点上的 CreativeType 属性。 |
height |
int32 此随播广告素材的高度(以像素为单位)。 |
width |
int32 此随播广告的宽度(以像素为单位)。 |
resource |
string 对于静态随播广告素材和 iframe 随播广告素材,这是指要加载和显示的网址。对于 HTML 随播广告,这将是应作为随播广告显示的 HTML 代码段。 |
type |
string 此随播广告素材的类型。它可以是静态、iframe 或 HTML。 |
InteractiveFile
InteractiveFile 包含应在广告播放期间显示的互动式广告素材(即 SIMID)的信息。JSON 表示法 |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
字段 | |
---|---|
resource |
string 指向互动式广告素材的网址。 |
type |
string 作为资源提供的文件的 MIME 类型。 |
variable_duration |
boolean 此广告素材是否可以要求延长时长。 |
ad_parameters |
string VAST 中 <AdParameters> 节点的值。 |