DAI API 目前為 Beta 版，可能無法在您的聯播網中使用。如需詳細資訊，請與您的客戶經理聯絡。如果平台適用，建議使用 IMA SDK。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

動態廣告插播 API

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

服務：dai.google.com

所有 URI 皆與 https://dai.google.com 相關

方法：stream

方法
`stream`	`POST /linear/v1/hls/event/{assetKey}/stream` 為指定活動 ID 建立動態廣告插播串流。

HTTP 要求

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

要求標頭

參數

參數
`api‑key`	`string` 建立串流時提供的 API 金鑰必須適用於發布商的聯播網。 API 金鑰可以透過下列格式，在 HTTP 授權標頭中傳遞，不必在要求主體中提供： Authorization: DCLKDAI key="<api-key>"

api‑key

string

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

API 金鑰可以透過下列格式，在 HTTP 授權標頭中傳遞，不必在要求主體中提供：

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

路徑參數

參數
`assetKey`	`string` 串流的事件 ID。注意：串流素材資源鍵也是 ID，可在 Ad Manager 使用者介面中找到。

要求主體

要求主體類型為 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 會傳回下列回應：

HTTP/1.1 204 No Content 媒體驗證成功，且所有 Ping 都已傳送。
HTTP/1.1 404 Not Found 如果要求因網址格式錯誤或過期而無法驗證媒體。
HTTP/1.1 404 Not Found 如果先前對這個 ID 的驗證要求成功。
HTTP/1.1 409 Conflict 如果其他要求目前正在傳送 Ping。

廣告媒體 ID (HLS)

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

在提出每項廣告驗證要求前，應將影格的完整文字內容附加至廣告驗證網址。

方法：metadata

metadata_url 的中繼資料端點會傳回用於建構廣告使用者介面的資訊。伺服器端信號傳送串流無法使用中繼資料端點，因為伺服器負責啟動廣告媒體驗證。

方法
`metadata`	`GET /{metadata_url}/{ad-media-id}` `GET /{metadata_url}` 擷取廣告中繼資料資訊。

HTTP 要求

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

GET https://{metadata_url}

查詢參數

參數
`delta_token`	選填	`string` 代表用戶端目前同步狀態的不透明權杖。如果提供權杖，伺服器只會傳回自權杖產生以來變更的中繼資料，並在回應中附上新的 `next_delta_token`。如果省略，伺服器會傳回整個 DVR 段落的完整中繼資料。

回應主體

如果成功，回應會傳回 PodMetadata 的例項。

使用中繼資料

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

google_1234567890

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

回覆資料

串流

Stream 用於以 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` 串流的資訊清單網址，用於擷取 HTTP 即時串流中的多變體播放清單，或 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 或 heartbeat_url 時的輪詢頻率 (以秒為單位)。

PodMetadata

PodMetadata 包含廣告、廣告插播和媒體 ID 標記的中繼資料資訊。

JSON 表示法
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], "next_delta_token": string, "obsolete_ad_break_ids": [], }

欄位
`tags`	`map[string, object(TagSegment)]` 依標記前置字元建立索引的標記區隔對應。
`ads`	`map[string, object(Ad)]` 依廣告 ID 編列索引的廣告地圖。
`ad_breaks`	`map[string, object(AdBreak)]` 廣告插播 ID 索引的廣告插播對應。
`next_delta_token`	`string` 用戶端在下次輪詢時使用的不透明權杖。
`obsolete_ad_break_ids`	`string` 過時的廣告插播時間點 ID 清單，應從用戶端快取中移除。

TagSegment

TagSegment 包含廣告、廣告插播和事件類型的參照。類型為「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` 有效的中斷類型為：pre、mid 和 post。
`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,
  "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` 選用布林值，表示目前項目為 Slate。
`icons`	`[object(Icon)]` 圖示清單，如果為空白則省略。
`wrappers`	`[object(Wrapper)]` Wrapper 清單，如果為空白則省略。
`universal_ad_id`	`object(UniversalAdID)` 選用通用廣告 ID。
`extensions`	`string` VAST 中所有 <Extension> 節點的選用清單。
`companions`	`[object(Companion)]` 可與此廣告一併顯示的選用隨播廣告。
`interactive_file`	`object(InteractiveFile)` 選用的互動式廣告素材 (SIMID)，應在廣告播放期間顯示。

圖示

Icon 包含 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, }

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

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` URI to javascript payload.
`api_framework`	`string` APIFramework 是執行驗證碼的影片架構名稱。
`browser_optional`	`boolean` 這個指令碼是否能在瀏覽器外執行。

TrackingEvent

TrackingEvent 包含用戶端應在特定情況下 Ping 的網址。

JSON 表示法
{ "event": string, "uri": string, }

欄位
`event`	`string` 追蹤事件的類型。
`uri`	`string` 要 Ping 的追蹤事件。

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)], }

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

動態廣告插播 API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

服務：dai.google.com

方法：stream

HTTP 要求

要求標頭

路徑參數

要求主體

回應主體

Open Measurement

方法：媒體驗證

HTTP 要求

回應主體

廣告媒體 ID (HLS)

方法：metadata

HTTP 要求

查詢參數

回應主體

使用中繼資料

回覆資料

串流

PodMetadata

TagSegment

AdBreak

廣告

圖示

ClickData

FallbackImage

Wrapper

驗證

JavaScriptResource

TrackingEvent

UniversalAdID

Companion

InteractiveFile

動態廣告插播 API