動態廣告插播廣告連播放送 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 指定目標參數 選用 Additional targeting parameters.
覆寫串流參數 選用 覆寫串流建立參數的預設值。
HMAC 驗證 選用 使用 HMAC 權杖進行驗證。

回應主體

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

Open Measurement

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

方法：廣告連播區隔

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

為指定的事件 ID 建立動態廣告插播串流。

HTTP 要求

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

路徑參數

參數
network_code string

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

custom_asset_key string

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

pod_identifier

支援下列格式：

pod/{integer}

目前廣告時段的數字 ID。從 1 開始，系統會為每個廣告插播事件逐步指派廣告連播 ID。

ad_break_id/{string}

目前廣告時段的字串 ID。
profile_name string

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

目前廣告連播中要求的區隔索引 (從 0 開始)。
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 權杖。
last 選填 boolean

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

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

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

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

註釋

  1. 初始化區隔不需要使用 sd。↩
  2. 如果事件已啟用無時間長度的廣告插播，則不需要 pd。↩

範例

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

回應主體

如果成功，回應主體會是可播放的串流片段，且符合要求中指定的格式和參數。

方法：HLS Pod 資訊清單

擷取直播的 HLS 廣告連播資訊清單，讓用戶端影片播放器載入及播放。

方法
GET GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8;

用於擷取廣告連播的 HTTP 即時串流多變化版本播放清單。

HTTP 要求

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

路徑參數

參數
network_code string

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

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

目前廣告時段的數字 ID。系統會從 1 開始，逐漸為每個廣告插播事件指派廣告插播 ID。

查詢參數

參數
stream_id 必要 string

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

廣告連播的時間長度 (以毫秒為單位)。
scte35 選用 string

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

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

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

回應主體

如果成功，回應主體會是 HTTP 即時串流多變化版本播放清單。

方法：DASH 廣告連播資訊清單

擷取直播的 MPEG-DASH 廣告連播資訊清單，讓用戶端影片播放器載入及播放。

方法
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd

用於擷取廣告連播的 MPEG-DASH MPD 播放清單。

HTTP 要求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

路徑參數

參數
network_code string

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

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

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

目前廣告時段的數字 ID。系統會從 1 開始，逐漸為每個廣告插播事件指派廣告插播 ID。

查詢參數

參數
pd 必要 integer

廣告連播的時間長度 (以毫秒為單位)。
scte35 選用 string

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

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

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

回應主體

如果成功，回應主體會是 MPEG-DASH mpd 播放清單。

方法：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 會傳回下列回應：

  • HTTP/1.1 204 No Content：如果媒體驗證成功且已傳送所有 Ping，則會傳回此值。
  • 如果要求因網址格式或過期而無法驗證媒體，則為 HTTP/1.1 404 Not Found。
  • HTTP/1.1 404 Not Found。
  • HTTP/1.1 409 Conflict：如果其他要求目前正在傳送連線偵測 (ping)。

廣告媒體 ID

廣告媒體 ID 會在獨立的媒體資料音軌中編碼，例如 HLS 傳輸串流的時間控管媒體資料，或 MP4 檔案的 emsg。廣告媒體 ID 一律以字串 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,
  "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 資訊清單網址範本用於產生網址，以便擷取串流的 Pod 資訊清單，對應至 HLS 中的多變數播放清單網址，或 DASH 中的 MPD。動態廣告插播類型為 POD_SERVING_MANIFEST 的直播事件才會填入。 https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

資訊清單格式是從 pod_manifest_url 擷取的資訊清單格式，可為 dash 或 hls。

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

廣告插播中的廣告數量。
Ad 會說明串流中的廣告。
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)，應在廣告播放期間顯示。

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

要進行 ping 的追蹤事件。

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