使用自訂整合

事前準備

本指南僅涵蓋未安裝 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。每個值都是一個物件,具有下列屬性:
  • ad:包含廣告媒體事件的廣告 ID。
  • ad_break_id:包含廣告媒體事件的廣告插播 ID。
  • type:廣告媒體事件類型。值為下列其中之一:
    • start:廣告已開始放送
    • firstquartile - 廣告完成率為 25%。
    • midpoint - 廣告完成率為 50%。
    • thirdquartile - 廣告完成率為 75%。
    • complete:廣告已結束。
    • progress:廣告播放期間每秒觸發一次。
ads 一組用於說明串流中廣告的鍵/值組合。每個鍵都是廣告 ID。每個值都是一個物件,具有下列屬性:
  • ad_break_id:包含廣告媒體事件的廣告插播 ID。
  • position:廣告在廣告插播中的順序。請注意,插播廣告中的首則廣告位置為 1
  • duration:廣告的持續時間,以浮點秒為單位。
  • title:廣告標題,如 VAST 中所定義。
  • description:廣告的說明,如 VAST 中所定義。
  • ad_system:VAST 中定義的廣告系統。
  • ad_system:廣告 ID,如 VAST 中所定義。
  • ad_system:VAST 中定義的廣告素材 ID。
  • clickthrough_url:使用者與廣告互動時要開啟的網址。
  • universal_ad_id:代表 VAST 中定義的通用廣告 ID 的物件。
ad_breaks 一組鍵/值組合,用於說明串流中會出現的廣告插播。每個鍵都是廣告插播 ID。每個值都是一個物件,具有下列屬性:
  • type:廣告插播類型。值為下列其中一種:
    • pre:代表片頭廣告。
    • mid:代表片中廣告。
    • post:代表片尾廣告。
  • duration:廣告插播的持續時間,以浮點秒為單位。
  • expected_duration:廣告插播的預期時間長度,以浮點秒為單位。
  • ads:廣告插播中包含的廣告數量。

請在每次輪詢後儲存這些值,以便在影片串流中關聯時間中繼資料事件。

要求範例 (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 事件:

  1. 將媒體事件儲存在佇列中,如果媒體播放器顯示,則儲存每個媒體 ID 及其時間戳記。
  2. 在播放器每次更新時,或在設定的頻率 (建議為 500 毫秒) 時,請比較事件時間戳記與播放頭,檢查媒體事件佇列中最近播放的事件。
  3. 針對已確認播放的媒體事件,請在儲存的廣告插播代碼中查詢媒體 ID,確認事件類型。請注意,廣告插播標記物件只包含媒體 ID 的截斷版本,且僅限於 google_ 前置字串後面的前 10 個數字,因此 ID3 媒體驗證 ID 與標記物件中的鍵並未直接比對。這麼做是為了避免在 ID3 事件到達前,傳送事件驗證 ping。如要產生廣告事件的完整媒體驗證網址,請將完整廣告事件 ID 附加至串流建立回應中的 media_verification_url 值。
  4. 使用「進度」事件,追蹤使用者是否處於廣告插播期間。請勿將這些事件傳送至媒體驗證端點,以免產生 HTTP 錯誤代碼。如果是其他事件類型,請將媒體 ID 附加至媒體驗證網址,並發出 GET 要求來追蹤播放。
  5. 從待播清單中移除媒體事件。

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:使用者代理程式參數會以瀏覽器專屬值的形式傳遞,而非底層平台。
  • rdididtypeis_lat:未正確傳遞裝置 ID,因此會限制下列功能的功能:
    • 展示頻率上限
    • 依序輪播廣告
    • 目標對象區隔和指定目標