動態廣告插播 VOD API

動態廣告插播 API 可讓您請求及追蹤 DAI 隨選影片 (VOD) 串流。支援 HLS 和 DASH 串流。

服務：dai.google.com

stream 方法的路徑與 https://dai.google.com 相關

方法：串流

方法
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

針對特定內容來源和影片 ID，建立 HTTP 即時串流動態廣告插播串流。

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

為特定的內容來源和影片 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 金鑰 必須是發布商聯播網的有效值。

系統不會在要求主體中提供 API 金鑰，而是改以 格式如下的 HTTP Authorization 標頭：

Authorization: DCLKDAI key="<api-key>"

路徑參數

參數
content-source string

串流的 CMS ID。

video-id string

串流的影片 ID。

要求主體

要求主體類型為 application/x-www-form-urlencoded，當中包含 參數

參數
dai-ssb 選用

設為 true 即可建立伺服器端信標串流。 預設值為 false。預設串流的追蹤 是在用戶端啟動與連線偵測 (ping)。
DFP 指定參數 選用 其他指定目標參數。
覆寫串流參數 選用 覆寫串流建立參數的預設值。
HMAC 驗證 選用 使用 HMAC 權杖進行驗證。

回應主體

如果成功，回應主體會包含新的 Stream。針對伺服器端信標串流，這個 Stream 只包含 stream_id 和 stream_manifest 欄位。

Open Measurement

Verifications 欄位包含公開資訊 非伺服器端信標串流的評估驗證。 Verifications 包含一或多個列出資源的 Verification 元素 和中繼資料必須透過第三方評估程式碼驗證廣告素材播放作業。 系統僅支援 JavaScriptResource。如需更多資訊 請前往 IAB Tech Lab 以及 VAST 4.1 規格。

方法：媒體驗證

在播放期間遇到廣告媒體 ID 後，請立即 使用 stream 中的 media_verification_url 要求 端點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。
  • HTTP/1.1 404 Not Found。
  • HTTP/1.1 409 Conflict：如果其他要求目前正在傳送連線偵測 (ping)。

廣告媒體 ID (HLS)

廣告媒體 ID 會使用鍵 TXXX，在 HTTP 即時串流時間戳記中繼資料內編碼。 僅供「使用者定義文字資訊」使用相輔相成。畫面的內容 「資料」不會加密，且開頭一律是 "google_" 這個文字。

畫面的完整文字內容應附加到 每個廣告驗證請求的 media_verification_url。

廣告媒體 ID (DASH)

廣告媒體 ID 會透過 DASH 的 EventStream 元素。

每個 EventStream 的配置 ID URI 皆為 urn:google:dai:2018。 其中包含的事件中含有 messageData 屬性，其中包含 廣告媒體 ID 開頭為 “google_”。「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
串流 ID。
total_duration
number
串流時間長度 (以秒為單位)。
content_duration
number
不含廣告的內容時間長度，以秒為單位。
valid_for
string
持續時間串流的有效期間，格式為「00h00m00s」格式。
valid_until
string
串流效期至 RFC 3339 格式。
subtitles
[object(Subtitle)]
字幕清單。如果留空，則省略。僅限 HTTP 即時串流。
hls_master_playlist
string
(已淘汰) HTTP 即時串流主要播放清單網址。使用 stream_manifest。僅限 HTTP 即時串流。
stream_manifest
string
串流的資訊清單。對應至 HTTP 即時串流中的主要播放清單和 DASH 中的 MPD。 此為「stream_id」以外的唯一的欄位回應中的 Pod 建立伺服器端信標串流
media_verification_url
string
媒體驗證網址。
apple_tv
object(AppleTV)
AppleTV 裝置專用的選用資訊。僅限 HTTP 即時串流。
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
有效的廣告插播類型：中、片頭和片尾。
start
number
廣告插播在串流中的位置 (以秒為單位)。
duration
number
廣告插播長度 (以秒為單位)。
ads
[object(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),
  "skip_metadata": object(SkipMetadata),
}
欄位
seq
number
廣告在廣告插播中的位置。
start
number
廣告在串流中的位置 (以秒為單位)。
duration
number
廣告長度，以秒為單位。
title
string
選用的廣告標題。
description
string
廣告說明 (選填)。
advertiser
string
廣告主 ID (選填)。
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)。
skip_metadata
object(SkipMetadata)
可略過廣告的選用中繼資料。如果有設定，就表示廣告 包含如何處理略過 UI 的說明指示 和追蹤事件。

活動

活動包含活動類型和顯示時間。
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 補充資訊檔案的選用網址。
webvtt
string
WebVTT 補充資訊檔案的選用網址。

SkipMetadata

SkipMetadata 會提供必要資訊，方便用戶端處理可略過廣告的略過事件。
JSON 表示法
{
  "offset": number,
  "tracking_url": string,
}
欄位
offset
number
偏移量表示播放器進入廣告的時間長度 (以秒為單位) 應該就能看到略過按鈕。如果 VAST 中未提供此值則會傳回。
tracking_url
string
TrackingURL 包含應對略過事件進行連線偵測 (ping) 的網址。

圖示

圖示包含 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
廣告系統 ID。
ad_id
string
用於包裝函式廣告的廣告 ID。
creative_id
string
用於包裝函式廣告的廣告素材 ID。
creative_ad_id
string
用於包裝函式廣告的廣告素材 ID。
deal_id
string
包裝函式廣告的選用交易 ID。

驗證

驗證功能包含 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
追蹤事件的類型。
uri
string
要連線偵測的追蹤事件。

UniversalAdID

UniversalAdID 是用來提供專屬廣告素材 ID， 和各個廣告系統之間的連線
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,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
欄位
click_data
object(ClickData)
此隨播廣告的點擊資料。
creative_type
string
<StaticResource> 上的 CreativeType 屬性 這是靜態的組合
height
int32
此隨播廣告的高度 (以像素為單位)。
width
int32
此隨播廣告的寬度 (以像素為單位)。
resource
string
如果是靜態和 iframe 隨播廣告，這是指要載入的網址 高度。如果是 HTML 隨播廣告，這段 HTML 程式碼片段應該是 以隨播廣告形式顯示。
type
string
此隨播廣告的類型。(可以是靜態、iframe 或 HTML)。
ad_slot_id
string
此隨播廣告的版位 ID。
api_framework
string
此夥伴適用的 API 架構。
tracking_events
[object(TrackingEvent)]
此隨播廣告的追蹤事件清單。

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
<AdParameters> 的值節點中的節點。