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

本頁面由 Cloud Translation API 翻譯而成。

動態廣告插播 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 金鑰，而是可以傳遞 API 金鑰 HTTP 授權標頭中，格式如下： Authorization: DCLKDAI key="<api-key>"

api‑key

string

建立串流時提供的 API 金鑰必須是發布商聯播網的有效值。

系統不會在要求主體中提供 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 欄位。這個欄位包含一或多個 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，保留用於「使用者定義文字資訊」相輔相成。畫面內容不會加密，且一律會以文字開頭 "google_"。

畫面中的所有文字內容都應附加到廣告驗證中送出任何廣告驗證要求之前的網址。

方法：metadata

metadata_url 的中繼資料端點會傳回用來建立廣告的資訊第一種是使用無代碼解決方案 AutoML 透過使用者介面建立機器學習模型中繼資料端點不適用於伺服器端信標串流，由伺服器負責啟動廣告媒體驗證

方法
`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 物件建立索引。

回應資料

串流

串流是用來轉譯內新建立串流的資源清單 YAML 或 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` (已淘汰) 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,
  "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` 選用清單，列出所有 <額外資訊>節點上的節點。
`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, }

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 包含客戶應該在某些情況下連線偵測 (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 會分類。

夥伴

隨播廣告包含可能顯示之隨播廣告的資訊以及廣告

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