Google DAI Pod 供應 API 可讓您執行由 Google Ads 技術提供的伺服器端廣告插播,同時保有自己的影片拼接控制權。
本指南會說明如何與 Pod 供應 API 互動,並透過 IMA DAI SDK 達到類似的功能。如有支援功能的特定問題,請與您的 Google 客戶經理聯絡。
Pod 供應 API 支援以 HLS 或 MPEG-DASH 串流通訊協定的 Pod 提供串流。本指南著重於 HLS 串流,並強調在特定步驟中 HLS 和 MPEG-DASH 的主要差異。
如要針對 VOD 串流,將 Pod 供應 API 整合至您的應用程式,請完成下列步驟:
向 Ad Manager 發出串流註冊要求
向串流註冊端點發出 POST 要求。接著您會收到一個 JSON 回應,其中包含串流 ID,並傳送至您的資訊清單操縱伺服器和相關聯的 Pod 供應 API 端點。
API 端點
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
路徑參數
{network_code} |
您的 Google Ad Manager 360 聯播網代碼 |
{custom_asset} |
在 Google Ad Manager 中與這個事件相關聯的自訂 ID。 |
表單編碼主體參數
一組選用的表單編碼 指定參數 。
回應 JSON
media_verification_url |
對播放追蹤事件進行連線偵測 (ping) 的基準網址。完整的媒體驗證網址就是將廣告事件 ID 附加至這個基準網址。 |
metadata_url |
用於要求廣告連播中繼資料的網址。 |
stream_id |
用來識別目前串流工作階段的字串。 |
valid_for |
與目前串流工作階段到期前的剩餘時間,以 dhms (天、小時、分鐘、秒) 的格式表示。舉例來說,2h0m0.000s 代表 2 小時。 |
valid_until |
目前串流工作階段的到期時間,以 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 格式的 ISO 8601 日期時間字串表示。 |
要求範例 (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
回應範例
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
如果發生錯誤,系統會傳回標準 HTTP 錯誤代碼,且不包含 JSON 回應主體。
剖析 JSON 回應並儲存相關值。
向資訊清單操控器要求串流資訊清單
每個資訊清單操控器都有不同的要求和回應格式。如要瞭解特定需求,請與您的操縱器供應商聯絡。如果您要實作自己的資訊清單操控工具,請參閱資訊清單操控工具指南,瞭解這個元件的相關規定。
一般而言,您需要將上述註冊端點傳回的串流 ID 傳遞至資訊清單操控器,才能建構工作階段專屬資訊清單。除非資訊清單操控工具明確指明,否則對資訊清單要求的回應就是包含內容和廣告的影片串流。
要求範例 (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
回應範例 (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
播放串流
將您從資訊清單操縱伺服器收到的資訊清單載入影片播放器,然後開始播放。
向 Ad Manager 請求廣告連播中繼資料
向步驟 1 中收到的 metadata_url
發出 GET
要求。您收到資訊清單操控工具提供的拼接資訊清單後,必須執行這個步驟。您會在回傳中收到包含下列參數的 JSON 物件:
tags |
串流中出現的所有廣告事件的一組鍵/值組合。鍵是廣告事件 ID 的前 17 個字元,會顯示在串流的定時中繼資料中;如果是 progress 類型的事件,則是完整廣告事件 ID。每個值都是一個物件,其中包含下列參數:
|
||||||||||||||||||
ads |
一組鍵/值組合,用來說明串流中顯示的所有廣告。這些鍵是與上述 tags 物件中找到的值相符的廣告 ID。每個值都是一個物件,其中包含下列參數:
|
||||||||||||||||||
ad_breaks |
一組鍵/值組合,用於說明串流中顯示的所有廣告插播。
這些鍵是廣告插播 ID,會與上述 tags 和 ads 物件中的值相符。每個值都是一個物件,其中包含下列參數:
|
儲存這些值,以在影片串流中與定時中繼資料事件建立關聯。
要求範例 (cURL)
curl https://dai.google.com/.../metadata
回應範例
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
監聽廣告事件
透過影片播放器的音訊/影片串流中觸發的廣告事件,監聽定時中繼資料。
如果是 MPEG-TS 串流,中繼資料會顯示為頻內 ID3 v2.3 標記。每個中繼資料標記都具有 ID TXXX
,值以 google_
字串開頭,後接一系列字元。這個值是廣告事件 ID,
TXXX
中的 XXX
不是預留位置。TXXX
字串是保留給「使用者定義文字」的 ID3 標記 ID。
ID3 代碼範例
TXXXgoogle_1234567890123456789
如為 MP4 串流,這些事件會以頻內電子郵件事件的形式傳送,模擬 ID3 v2.3 標記。每個相關訊息方塊的 scheme_id_uri
值分別為 https://aomedia.org/emsg/ID3
或 https://developer.apple.com/streaming/emsg-id3
,以及開頭為 ID3TXXXgoogle_
的 message_data
。這個 message_data
值不含 ID3TXXX
前置字串,就是廣告事件 ID。
電子信箱範例
視媒體播放器媒體庫而定,資料結構可能會有所不同。
如果廣告事件 ID 是 google_1234567890123456789
,回應會如下所示:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
部分媒體播放器程式庫會自動顯示 emsg 事件,將 ID3 標記模擬為原生 ID3 標記。在此情況下,MP4 串流顯示的 ID3 標記與 MPEG_TS 相同。
更新用戶端影片播放器應用程式的 UI
每個廣告事件 ID 都符合步驟 4 中 tags
物件的鍵。比對這些值的程序有兩個步驟:
查看
tags
物件,找出與完整廣告事件 ID 相符的鍵。如果找到相符項目,請擷取事件類型及其相關聯的ad
和ad_break
物件。這些事件應具有progress
類型。如果找不到與完整廣告事件 ID 相符的項目,請檢查
tags
物件,找出與廣告事件 ID 前 17 個字元相符的鍵。擷取事件類型以及相關聯的ad
和ad_break
物件。這樣應會擷取類型不含progress
以外的所有事件。利用擷取到的資訊來更新玩家的使用者介面。舉例來說,當您收到
start
或第一個progress
事件時,請隱藏玩家的搜尋控制項,並顯示說明目前廣告在廣告插播中的位置的重疊元素,例如「第 1 個廣告 (共 3 個)。」
廣告事件 ID 範例
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
代碼物件範例
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
傳送媒體驗證連線偵測 (ping)
每次收到 progress
以外的廣告事件時,都必須將媒體驗證連線偵測 (ping) 傳送至 Ad Manager。
如要產生廣告事件的完整媒體驗證網址,請將完整的廣告事件 ID 附加至串流註冊回應中的 media_verification_url
值。
使用完整網址發出 GET 要求。如果驗證要求成功,您會收到 HTTP 回應,狀態碼為 202
。否則,您會收到 HTTP 錯誤代碼 404
。
要求範例 (cURL)
curl https://{...}/media/google_5555555555123456789
成功回應範例
HTTP/1.1 202 Accepted