動態廣告插播 VOD API

動態廣告插播 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 串流。

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 金鑰。

比起在要求主體中提供 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 欄位包含非伺服器端信標串流的 Open 評估驗證相關資訊。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 鍵以 HLS 定時中繼資料編碼，將保留給「使用者定義的文字資訊」頁框。影格的內容將未經加密，且一律以 "google_" 文字開頭。

每個廣告驗證請求都必須將影格的完整文字內容附加至 media_verification_url。

廣告媒體 ID (DASH)

系統會使用 DASH 的 EventStream 元素，在資訊清單中插入廣告媒體 ID。

每個 EventStream 都會有 urn:google:dai:2018 的配置 ID URI。這些事件包含具有 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

串流持續時間適用於「00h00m00s」格式。
valid_until string

串流有效期限，採用 RFC 3339 格式。
subtitles [object(Subtitle)]

字幕清單。如果留空，則予以省略。僅限 HTTP 即時串流。
hls_master_playlist string

(已淘汰) HLS 主要播放清單網址。使用 stream_manifest。僅限 HTTP 即時串流。
stream_manifest string

串流的資訊清單。對應 HLS 和 DASH 中的 MPD 主要播放清單。 建立伺服器端信標串流時，回應中會顯示「stream_id」之外的唯一欄位。
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

TML 補充資訊檔案的選用網址。
webvtt string

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

SkipMetadata

SkipMetadata 提供客戶處理可略過廣告的略過事件所需的資訊。
JSON 表示法
{
  "offset": number,
  "tracking_url": string,
}
欄位
offset number

「偏移」表示播放器應等待廣告顯示略過按鈕所需的時間 (以秒為單位)。如果 VAST 中未提供，則可略過。
tracking_url string

TrackingURL 包含應在略過事件上連線偵測的網址。

圖示

圖示包含 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，就不會包含該 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

傳遞至 Bootstrap 驗證碼的不透明字串。

JavaScriptResource

JavaScriptResource 包含透過 JavaScript 驗證的資訊。
JSON 表示法
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
欄位
script_url string

JavaScript 酬載的 URI。
api_framework string

API Framework 是執行驗證碼的影片架構名稱。
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 所在註冊網站的網址。

Companion

隨播廣告包含隨播廣告可能與廣告一併顯示的資訊。
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

如果這是靜態類型的隨播廣告，就在 VAST 中的 <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

VAST 中 <AdParameters> 節點的值。