事前準備
本指南僅涵蓋未安裝 IMA DAI SDK 的播放操作說明。
請先確認您已完成「將 Google Ad Manager (GAM) 與直播串流整合」中的步驟。
如果 IMA SDK 不適用於指定平台,您必須讓應用程式呼叫必要的 API,並自行觸發廣告曝光。
如要執行這項操作,您需要提供下列資訊:
位置 |
建立即時設定的
Google Cloud 區域
:
LOCATION
|
專案編號 |
使用 Video Stitcher API 的 Google Cloud 專案專案編號:
PROJECT_NUMBER
|
OAuth 權杖 |
服務帳戶的短期 OAuth 權杖,具有 Video Stitcher 使用者角色:
OAUTH_TOKEN 進一步瞭解如何 建立短期 OAuth 權杖。 |
聯播網代碼 |
用於要求廣告的 Ad Manager 聯播網代碼:
NETWORK_CODE
|
直播設定 ID |
建立直播活動時指定的直播設定 ID:
LIVE_CONFIG_ID
|
自訂素材資源金鑰 |
使用 Video Stitcher API 為直播活動
建立設定
時,Ad Manager 自訂素材資源鍵會在這個過程中產生:
CUSTOM_ASSET_KEY
|
向 Ad Manager 提出串流註冊要求
向串流註冊端點發出 POST 要求。系統會傳回 JSON 回應,其中包含要傳送至影片拼接 API 的串流 ID。
API 端點
POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
路徑參數
NETWORK_CODE |
您的 Google Ad Manager 360 聯播網代碼:
NETWORK_CODE
|
CUSTOM_ASSET_KEY |
在 Google Ad Manager 中與此事件相關聯的自訂 ID:
CUSTOM_ASSET_KEY
|
表單編碼的內容參數
選用的表單編碼 指定目標參數 組合。
回應 JSON
media_verification_url |
用於連線偵測 (ping) 播放追蹤事件的基準網址。只要將廣告事件 ID附加到這個基礎網址,即可建立完整的媒體驗證網址。MEDIA_VERIFICATION_URL
|
metadata_url |
要求廣告連播中繼資料的網址。
METADATA_URL
|
polling_frequency |
建議的「metadata_url」輪詢頻率 (以毫秒為單位)。
POLLING_FREQUENCY
|
stream_id |
用來識別目前串流工作階段的字串。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/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream
回應範例
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
發生錯誤時,系統會傳回標準 HTTP 錯誤代碼,但不會傳回 JSON 回應主體。
剖析 JSON 回應並儲存相關值。
產生工作階段播放 URI
向 Video Stitcher API 的 /livesessions
端點提出 POST 要求,以建立新的直播工作階段。系統會傳回 JSON 回應,其中包含要載入至影片播放器的串流資訊清單。
API 端點
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
路徑參數
PROJECT_NUMBER |
使用 Video Stitcher API 的 Google Cloud 專案專案編號:
PROJECT_NUMBER
|
LOCATION |
建立即時設定的
Google Cloud 區域
:
LOCATION
|
授權標頭參數
OAUTH_TOKEN |
服務帳戶的短期 OAuth 權杖,具有 Video Stitcher 使用者角色:
OAUTH_TOKEN |
以 JSON 編碼的內容參數
liveConfig |
字串,其中包含專案編號、位置和即時設定 ID,格式如下:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
|
adTracking |
將其設為 "CLIENT" 可啟用用戶端追蹤功能。 |
gamSettings |
包含串流 ID 的物件,格式如下:
{"streamId":"STREAM_ID"}
|
回應 JSON
name |
直播工作階段的名稱,包含工作階段 ID。 |
playUri |
拼接串流資訊清單的 URI,可載入至影片播放器進行播放。PLAY_URI
|
liveConfig |
在要求主體中傳送至 API 的相同 liveConfig 字串。 |
gamSettings |
在要求主體中傳送至 API 的相同 gamSettings 物件。 |
要求範例 (cURL)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer OAUTH_TOKEN" \
-d '@request.json' \
https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
request.json
{
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
"adTracking": "CLIENT",
"gamSettings": {
"streamId": "STREAM_ID"
}
}
回應範例
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
"playUri": PLAY_URI,
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
"gamSettings": {
"streamId": STREAM_ID
}
}
收到回應後,您可以參照回應物件的 playUri
欄位中的工作階段播放 URI,播放已加入廣告的直播。
Video Stitcher API 會為每個要求產生專屬的工作階段 ID,可從回應物件的 name
欄位最後一個部分擷取。
閒置工作階段會在 5 分鐘後失效。如果在一段時間內未有任何資訊清單擷取作業,系統就會將工作階段視為閒置。
輪詢新的 AdBreak 中繼資料
應用程式負責擷取每個廣告插播的中繼資料,以便瞭解需要觸發哪些曝光。為達成這項目標,您需要設定計時器,定期輪詢 DAI API metadata_url
以取得新廣告資訊。輪詢的間隔會在串流註冊回應的 polling_frequency
欄位中指定。
您會收到 JSON 物件,其中包含下列參數:
tags |
一組鍵/值組合,用於說明串流中會發生的廣告媒體事件。每個鍵都包含廣告媒體 ID 的前 17 個字元,這些字元會顯示在串流的 ID3 中繼資料中;如果是 `progress` 事件,則會包含整個廣告媒體 ID。每個值都是一個物件,具有下列屬性:
|
ads |
一組用於說明串流中廣告的鍵/值組合。每個鍵都是廣告 ID。每個值都是一個物件,具有下列屬性:
|
ad_breaks |
一組鍵/值組合,用於說明串流中會出現的廣告插播。每個鍵都是廣告插播 ID。每個值都是一個物件,具有下列屬性:
|
請在每次輪詢後儲存這些值,以便在影片串流中關聯時間中繼資料事件。
要求範例 (cURL)
curl https://dai.google.com/.../metadata/
回應範例
{
"tags":{
"google_0492266569":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"firstquartile"
},
"google_1560331148":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"thirdquartile"
},
"google_1877686714378797835":{
"ad":"0000229836_slate",
"ad_break_id":"0000229836",
"type":"progress"
},
"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"progress"
},
"google_2032765498":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"midpoint"
},
...
"google_5646900623":{
"ad":"0000229837_ad1",
"ad_break_id":"0000229837",
"type":"complete"
}
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15.01,
"title":"truman-e2e-creativeset4",
"description":"truman-e2e-creativeset4 ad",
"ad_system":"GDFP",
"ad_id":"39066884",
"creative_id":"58092079124",
"clickthrough_url":"https://pubads.g.doubleclick.net/...",
"universal_ad_id":{
"id_value":"58092079124",
"id_registry":"GDFP"
}
},
"0000229834_slate":{
"ad_break_id":"0000229834",
"position":-1,
"duration":14.974977777,
"slate":true
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15.01,
"expected_duration":29.984977776999997,
"ads":1
},
...
}
}
監聽 ID3 事件並追蹤播放事件
如要驗證影片串流中是否發生特定事件,請按照下列步驟處理 ID3 事件:
- 將媒體事件儲存在佇列中,如果媒體播放器顯示,則儲存每個媒體 ID 及其時間戳記。
- 在播放器每次更新時,或在設定的頻率 (建議為 500 毫秒) 時,請比較事件時間戳記與播放頭,檢查媒體事件佇列中最近播放的事件。
- 針對已確認播放的媒體事件,請在儲存的廣告插播代碼中查詢媒體 ID,確認事件類型。請注意,廣告插播標記物件只包含媒體 ID 的截斷版本,且僅限於 google_ 前置字串後面的前 10 個數字,因此 ID3 媒體驗證 ID 與標記物件中的鍵並未直接比對。這麼做是為了避免在 ID3 事件到達前,傳送事件驗證 ping。如要產生廣告事件的完整媒體驗證網址,請將完整廣告事件 ID 附加至串流建立回應中的 media_verification_url 值。
- 使用「進度」事件,追蹤使用者是否處於廣告插播期間。請勿將這些事件傳送至媒體驗證端點,以免產生 HTTP 錯誤代碼。如果是其他事件類型,請將媒體 ID 附加至媒體驗證網址,並發出 GET 要求來追蹤播放。
- 從待播清單中移除媒體事件。
API 端點
GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com
路徑參數
MEDIA_VERIFICATION_URL |
串流註冊端點在 media_verification_url 欄位中傳回的值:
MEDIA_VERIFICATION_URL
|
AD_MEDIA_ID |
完整的廣告媒體 ID,如串流的 ID3 中繼資料所示:
AD_MEDIA_ID
|
預期的回傳值
HTTP/1.1 204 No Content |
成功的空白回應。 |
HTTP/1.1 404 Not Found |
系統無法辨識媒體驗證 ID。 |
HTTP/1.1 409 Conflict |
媒體驗證 ID 已傳送。 |
要求範例 (cURL)
curl MEDIA_VERIFICATION_URLAD_MEDIA_ID
回應範例
HTTP/1.1 204 No Content
限制
如果在 WebView 中使用 API,則以下限制適用於指定目標:
- UserAgent:使用者代理程式參數會以瀏覽器專屬值的形式傳遞,而非底層平台。
- rdid、idtype、is_lat:未正確傳遞裝置 ID,因此會限制下列功能的功能:
- 展示頻率上限
- 依序輪播廣告
- 目標對象區隔和指定目標