動態廣告插播 API

動態廣告插播 API 可讓您請求及追蹤 DAI 線性 (LIVE) 串流。

服務：dai.google.com

以下皆為與 https://dai.google.com 相對的 URI

方法：串流

方法
stream POST /linear/v1/hls/event/{assetKey}/stream

為特定事件 ID 建立 DAI 串流。

HTTP 要求

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

要求標頭

參數
api‑key string

建立串流時提供的 API 金鑰，必須適用於發布商的聯播網。

除了在要求主體中提供 API 金鑰，您也可以採用以下格式在 HTTP 授權標頭中傳遞 API 金鑰：

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

路徑參數

參數
assetKey string

串流的事件 ID。
注意：串流資產金鑰是可在 Ad Manager UI 中找到的 ID。

要求主體

要求主體類型為 application/x-www-form-urlencoded，包含下列參數：

參數
dai-ssb 選用

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

回應主體

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

Open Measurement

DAI API 的 Verifications 欄位中包含 Open Measurement 驗證的資訊。這個欄位包含一或多個 Verification 元素，該元素會列出執行第三方評估程式碼所需的資源和中繼資料，以確認廣告素材播放。系統僅支援 JavaScriptResource。詳情請參閱 IAB Tech Lab 和 VAST 4.1 規格。

方法：媒體驗證

在播放期間遇到廣告媒體 ID 後，請立即使用從上述 stream 端點取得的 media_verification_url 提出要求。而伺服器端信標串流則不需要這些要求，因為伺服器會在其中啟動媒體驗證。

向 media verification 端點發出的要求皆為冪等。

方法
media verification GET /{media_verification_url}/{ad_media_id}

向 API 通知媒體驗證事件。

HTTP 要求

GET https://{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_" 開頭。

在發出廣告驗證要求之前，請將畫面的完整文字內容附加至廣告驗證網址後方。

方法：metadata

metadata_url 的中繼資料端點會傳回用於建立廣告 UI 的資訊。中繼資料端點不適用於伺服器端信標串流，因為伺服器負責啟動廣告媒體驗證。

方法
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

擷取廣告中繼資料資訊。

HTTP 要求

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

回應主體

如果成功，回應會傳回 PodMetadata 的執行個體。

使用中繼資料

中繼資料有三個獨立的區段：tags、ads 以及廣告 breaks。資料的進入點為 tags 區段。然後反覆查看各標記，找出第一個項目名稱為影片串流中廣告媒體 ID 前置字元。舉例來說，您可能會有如下所示的廣告媒體 ID：

google_1234567890

然後找出名為 google_12345 的標記物件。在這個例子中，這個值與您的廣告媒體 ID 相符。找到正確的廣告媒體前置字元物件後，您可以查詢廣告 ID、廣告插播 ID 和事件類型。接著，系統會使用廣告 ID 為 ads 物件建立索引，並使用廣告插播 ID 為 breaks 物件建立索引。

回應資料

串流

串流是用來轉譯 JSON 格式新串流的資源清單。
JSON 表示法
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
欄位
stream_id string

GAM 串流 ID。
stream_manifest string

串流的資訊清單網址，用於擷取 HLS 中的多變數播放清單，或擷取 DASH 中的 MPD 播放清單。
hls_master_playlist string

(已淘汰) HTTP 即時串流多變化版本播放清單網址。請改用「stream_manifest」。
media_verification_url string

媒體驗證網址，用來做為追蹤播放事件的基礎端點。
metadata_url string

中繼資料網址，用於輪詢近期串流廣告事件的定期資訊。
session_update_url string

這個工作階段的更新網址，用來更新這個串流的指定目標參數。 系統會在初始串流建立請求期間，擷取指定目標參數的原始值。
polling_frequency number

輪詢頻率 (以秒為單位)，若要求 metadata_url from 或 Heartbeat_url。

PodMetadata

PodMetadata 包含廣告、廣告插播和媒體 ID 標記的中繼資料資訊。
JSON 表示法
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
欄位
tags map[string, object(TagSegment)]

依標記前置字元建立索引的標記區隔對應。
ads map[string, object(Ad)]

按廣告 ID 建立索引的廣告對應。
ad_breaks map[string, object(AdBreak)]

按廣告插播 ID 建立索引的廣告插播對應項目。

TagSegment

TagSegment 包含廣告的參照、廣告插播，以及事件類型。 請勿對廣告媒體驗證端點發出含有 type="progress" 的 TagSegment 呼叫。
JSON 表示法
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
欄位
ad string

這個代碼的廣告 ID。
ad_break_id string

這個代碼的廣告插播 ID。
type string

這個代碼的事件類型。

AdBreak

AdBreak 是指串流中的單一廣告插播，其中包含時間長度、類型 (中/前/後) 和廣告數量。
JSON 表示法
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
欄位
type string

有效的廣告插播類型：片頭、片中和片尾。
duration number

這個廣告插播的廣告總長度 (以秒為單位)。
expected_duration number

預期的廣告插播長度 (以秒為單位)，包括所有廣告和任何插入畫面。
ads number

廣告插播中的廣告數量。
廣告描述串流中的廣告。
JSON 表示法
{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
欄位
ad_break_id string

這個廣告插播的 ID。
position number

這則廣告在廣告插播中的位置，從 1 開始。
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

選填的到達網址。
click_tracking_urls string

選用的點擊追蹤網址。
verifications [object(Verification)]

非必要的 Open Measurement 驗證項目，其中會列出執行第三方評估程式碼所需的資源和中繼資料，以驗證廣告素材播放。
slate boolean

非必要的布林值，用來表示目前項目為插入畫面。
icons [object(Icon)]

圖示清單 (留空時省略)。
wrappers [object(Wrapper)]

如果為空白，省略包裝函式清單。
universal_ad_id object(UniversalAdID)

選用通用廣告 ID。
extensions string

VAST 中所有 <Extension> 節點的選用清單。
companions [object(Companion)]

可與這則廣告一起顯示的選用隨播廣告。
interactive_file object(InteractiveFile)

應在廣告播放期間顯示的選擇性互動式廣告素材 (SIMID)。

圖示

圖示包含 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 包含用戶端在特定情況下應連線偵測的網址。
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

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