動態廣告插播 API

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

服務：dai.google.com

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

方法：stream

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

比起在要求主體中提供 API 金鑰，API 金鑰能以下列格式透過 HTTP Authorization 標頭傳送：

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

路徑參數

參數
assetKey string

串流的事件 ID。
注意：串流素材資源金鑰是一種 ID，也可以在 Ad Manager UI 中找到。

要求主體

要求主體的類型為 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_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

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

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

用於輪詢近期直播廣告事件的中繼資料網址。
session_update_url string

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

要求 metadata_url 或 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，就不會包含該 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> 節點的值。