DAI API 目前為 Beta 版,可能未在您的聯播網中推出。如需詳細資訊,請與您的客戶經理聯絡。我們建議採用 IMA SDK 的平台。

動態廣告插播 VOD API

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

有了動態廣告插播 API,您就能請求和追蹤動態廣告插播隨選影片 (VOD) 串流。支援 HLS 和 DASH 串流。

服務:dai.google.com

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

方法:串流

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

為特定內容來源和影片 ID 建立 HLS DAI 串流。

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: 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_idstream_manifest 欄位。

Open Measurement

Verifications 欄位包含非伺服器端信標串流的 Open Measurement 驗證資訊。Verifications 包含一或多個 Verification 元素,其中列出使用第三方評估程式碼驗證廣告素材播放所需的資源和中繼資料。 僅支援 JavaScriptResource。詳情請參閱 IAB 技術研究室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 會傳回下列回應:

  • 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)

廣告媒體 ID 會使用 HLS 金鑰 TXXX 在 HLS 時間中繼資料中編碼,並保留給「使用者定義的文字資訊」頁框。影格的內容不會經過加密,而且一律以 "google_" 文字開頭。

針對每個廣告驗證請求,頁框的所有內容都必須附加到 media_verification_url

廣告媒體 ID (DASH)

只要使用 DASH 的 EventStream 元素,即可在廣告清單中插入廣告媒體 ID。

每個 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

串流 ID。
total_duration number

串流持續時間 (以秒為單位)
content_duration number

內容 (不含廣告) 的長度,以秒為單位。
valid_for string

持續時間串流的格式為「quot;00h00m00s"」格式。
valid_until string

串流的有效日期,格式為 RFC 3339。
subtitles [object(Subtitle)]

字幕清單。如果空白,則會略過。僅限 HLS。
hls_master_playlist string

(已淘汰) HLS 主要播放清單網址。使用 Stream_manifest。僅限 HLS。
stream_manifest string

串流的資訊清單。對應於 HLS 中的主要播放清單和 DASH 中的 MPD。
media_verification_url string

媒體驗證網址。
apple_tv object(AppleTV)

Apple Apple 裝置的專屬資訊。僅限 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

有效的廣告插播類型包括:中間、預先和發布。
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),
}
欄位
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。

圖示

圖示包含 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 包含圖示點擊的相關資訊。
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。

活動

事件包含事件類型和事件的呈現時間。
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' or 'de'
language_name string

語言的說明名稱。如果同一種語言有多個字幕,這會區分一組特定的字幕
ttml string

TTML 補充檔案的選用網址。
webvtt string

WebVTT 補充資訊檔案的選用網址。

驗證

驗證包含 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

URI 至 JavaScript 酬載。
api_framework string

APIFramework 是代表驗證碼的影片架構名稱。
browser_optional boolean

這個指令碼能否在瀏覽器以外的位置執行。

追蹤事件

TrackingEvent 包含應在某些情況下由用戶端進行連線偵測 (ping) 的網址。
JSON 表示法
{
  "event": string,
  "uri": string,
}
欄位
event string

追蹤事件的類型,目前僅有 VAST 4.1 規格中指定的選項為「verificationNotExecuted&quot」。
uri string

要連線的追蹤事件。

通用廣告 ID

UniversalAdID 提供不重複的廣告素材 ID,用來維護整個廣告系統。
JSON 表示法
{
  "id_value": string,
  "id_registry": string,
}
欄位
id_value string

所選廣告的通用廣告 ID。
id_registry string

這個字串是用來識別註冊網站登錄的註冊資料庫網址。#29;