動態廣告插播 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 金鑰,您也可以採用以下格式在 HTTP 授權標頭中傳遞 API 金鑰: Authorization: DCLKDAI key="<api-key>" |
路徑參數
參數 | |
---|---|
assetKey |
string 串流的事件 ID。 |
要求主體
要求主體類型為 application/x-www-form-urlencoded
,包含下列參數:
參數 | ||
---|---|---|
dai-ssb |
選用 | 設為 |
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
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 (已淘汰) HTTP 即時串流多變化版本播放清單網址。請改用「stream_manifest」。 |
media_verification_url |
string 媒體驗證網址,用來做為追蹤播放事件的基礎端點。 |
metadata_url |
string 中繼資料網址,用於輪詢近期串流廣告事件的定期資訊。 |
session_update_url |
string 這個工作階段的更新網址,用來更新這個串流的指定目標參數。 系統會在初始串流建立請求期間,擷取指定目標參數的原始值。 |
polling_frequency |
number 輪詢頻率 (以秒為單位),若要求 metadata_url from 或 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,則不會納入擷取鍵。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 包含用戶端在特定情況下應連線偵測的網址。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 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> 節點的值。 |