動態廣告插播廣告連播放送 Live API

動態廣告插播 API 可讓您請求及追蹤 DAI 直播。

服務：dai.google.com

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

方法：串流

方法
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

註冊 DAI DAI 廣告連播放送直播工作階段。

HTTP 要求

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

路徑參數

參數
network_code string

發布商的 Google Ad Manager 聯播網代碼。

custom_asset_key string

在 Google Ad Manager 中與這個事件相關聯的自訂 ID。

要求主體

要求主體類型為 application/x-www-form-urlencoded，當中包含 參數

參數
DFP 指定參數 選用 其他指定目標參數。
覆寫串流參數 選用 覆寫串流建立參數的預設值。
HMAC 驗證 選用 使用 HMAC 權杖進行驗證。

回應主體

如果成功，回應主體會包含新的 Stream 物件。

Open Measurement

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

方法：廣告連播片段

方法
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

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

HTTP 要求

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

路徑參數

參數
network_code string

發布商的 Google Ad Manager 聯播網代碼。

custom_asset_key string

在 Google Ad Manager 中與這個事件相關聯的自訂 ID。

pod_id integer

目前廣告插播的數字 ID。廣告連播 ID 為 並從 1 開始，依序為每個事件指派及指派對象。
profile_name string

名稱 的 Google Ad Manager DAI 編碼設定檔。 編碼設定檔必須是已設定的其中一個編碼設定檔 選取的事件

segment_number integer

目前廣告連播中的請求區隔索引 (起始點為 設為零
segment_format string

與要求的區隔格式相關聯的副檔名。 接受的副檔名包括：ts、mp4、 vtt、aac、ac3 或 eac3。

查詢參數

參數
stream_id 必要 string

目前使用者工作階段的串流 ID。這個值會由 對 stream 端點傳送成功的要求。
sd required1 integer

所請求區隔的時間長度，以毫秒為單位。
so 選用

在廣告連播中，要求區隔的偏移量 (以毫秒為單位)。 如果您省略 so 參數，該參數會依照 將片段時間長度乘以區隔編號。
pd 必要2 integer

廣告連播的時間長度 (以毫秒為單位)。
auth-token 必要 string

帶正負號的網址編碼 HMAC 權杖 相應數量的 Deployment
last 選用 boolean

指出廣告插播中的最後一個區段。針對所有客戶省略此參數 其他區隔
scte35 選用 string

這個廣告插播時間點使用 Base64 編碼的 SCTE-35signal。
cust_params 選用 string

一組鍵/值組合，用於 Ad Manager 廣告活動指定目標。這些 組合必須以網址編碼查詢字串表示。

範例：
參數
  • section = sports
  • 網頁 = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

註釋

  1. 初始化區隔不需要使用 sd。 ↩
  2. 如果事件不含持續時間的廣告，則不需要 pd 中斷點。 ↩

回應主體

如果成功，回應主體會是與 要求中指定的格式和參數。

方法：DASH 廣告連播時段範本

方法
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

向 Google Ad Manager 要求 DASH 時段範本。這個範本 包含必須填入串流參數的巨集。一次 系統會填入這些巨集，範本會變成廣告時段時段， 可以合併至您的 DASH 資訊清單

HTTP 要求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

路徑參數

參數
network_code string

發布商的 Google Ad Manager 聯播網代碼。

custom_asset_key string

在 Google Ad Manager 中與這個事件相關聯的自訂 ID。

查詢參數

參數
stream_id 必要 string

目前使用者工作階段的串流 ID。這個值會由 對 stream 端點傳送成功的要求。

回應主體

如果成功，回應主體會包含新的 PodTemplateResponse 物件。

方法：媒體驗證

在播放期間遇到廣告媒體 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 (如果先前針對這個 ID 提出驗證要求) 成功。
  • HTTP/1.1 409 Conflict：如果其他要求已在此傳送連線偵測 (ping) 讓應用程式從可以最快做出回應的位置 回應使用者要求

廣告媒體 ID

廣告媒體 ID 將編碼成獨立的中繼資料音軌，時效性 HLS 傳輸串流的中繼資料，或是 emsg 為 mp4 檔案。廣告媒體 ID 開頭一律是 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,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
欄位
stream_id
string
GAM 串流 ID。
media_verification_url
string
媒體驗證網址，用來做為追蹤播放事件的基礎端點。
metadata_url
string
中繼資料網址，用於輪詢近期串流廣告事件的定期資訊。
session_update_url
string
工作階段的更新網址，用來更新這個串流的指定目標參數。 系統會在初始串流建立請求期間，擷取指定目標參數的原始值。
heartbeat_url
string
心跳網址網址，用於保持伺服器端信標串流運作。 必須每 {PollingFrequency} 秒進行一次連線偵測 (ping)。 系統會針對伺服器端信標串流填入資料。
polling_frequency
number
輪詢頻率 (以秒為單位)，可用來要求 metadata_url 或 Heartbeat_url。
pod_manifest_url
string
廣告連播資訊清單網址範本可用來產生網址，以擷取串流的 Pod 資訊清單。 對應 DASH 中的多變化版本播放清單網址或 DASH 中的 MPD 網址。 會填入動態廣告插播類型 POD_SERVING_MANIFEST 的直播活動。 https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format
string
資訊清單格式是從 pod_manifest_url 擷取的資訊清單格式。 破折號或 hl 的名稱。

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
選用清單，列出所有 <額外資訊>節點上的節點。
companions
[object(Companion)]
可與這則廣告一併顯示的選用隨播廣告。
interactive_file
object(InteractiveFile)
應在廣告播放期間顯示的選擇性互動式廣告素材 (SIMID)。

PodTemplateResponse

PodTemplateResponse 代表傳回 VTP 的 JSON 酬載，以利進行 Pod 拼接。
JSON 表示法
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
欄位
dash_period_template
string
DashPeriodTemplate 是 XML 範本，用於在拼接前填入適當資料的期間。
segment_duration_ms
int64
SegmentDurationMS 是指週期區隔的持續時間 (以毫秒為單位)。

圖示

圖示包含 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 包含客戶應該在某些情況下連線偵測 (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)],
}
欄位
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> 的值節點中的節點。