使用自訂整合

事前準備

本文件僅涵蓋未安裝 IMA DAI SDK 的播放操作說明。

請先確認您已完成「將 Google Ad Manager (GAM) 與 VOD 素材資源整合」中的步驟。

如果 IMA SDK 不適用於您指定的平台，您必須讓應用程式自行呼叫必要的 API，並觸發廣告媒體驗證。

如要執行這項操作，您需要提供下列資訊：

位置 建立即時設定的 Google Cloud 區域 ：
LOCATION
專案編號 使用 Video Stitcher API 的 Google Cloud 專案專案編號：
PROJECT_NUMBER
OAuth 權杖 服務帳戶的短期 OAuth 權杖，具有 Video Stitcher 使用者角色： 
OAUTH_TOKEN
進一步瞭解如何 建立短期 OAuth 權杖。
聯播網代碼 用於要求廣告的 Ad Manager 聯播網代碼：
NETWORK_CODE
VOD 設定 ID 建立 VOD 串流事件時指定的 VOD 設定 ID：
VOD_CONFIG_ID

向 Ad Manager 提出串流註冊要求

向串流註冊端點發出 POST 要求。系統會傳回 JSON 回應，其中包含要傳送至資訊清單操控伺服器和相關 Pod 服務 API 端點的串流 ID。

API 端點

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

路徑參數

NETWORK_CODE 您的 Google Ad Manager 360 聯播網代碼

以 JSON 編碼的內容參數

targeting_parameters
一組選用的 JSON 編碼指定目標參數。

回應 JSON

media_verification_url 用於連線偵測 (ping) 播放追蹤事件的基準網址。只要將廣告事件 ID附加到這個基本網址，即可建立完整的媒體驗證網址。MEDIA_VERIFICATION_URL
metadata_url 要求廣告連播中繼資料的網址。 METADATA_URL
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/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

回應範例

{
  "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 回應並儲存相關值。

產生 Cloud Video Stitcher VOD 工作階段

向 VOD 工作階段註冊端點發出 POST 要求。系統會傳回 JSON 回應，其中包含串流資訊清單 URI，以及廣告插播、廣告和廣告事件的中繼資料。

API 端點

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

路徑參數

PROJECT_NUMBER 您的 Google Cloud 專案編號。
LOCATION 您的 Google Cloud 區域。
NETWORK CODE Google Ad Manager 360 聯播網代碼。

以 JSON 編碼的內容參數

vodConfig 字串，包含專案編號、位置和 VOD 設定 ID，格式如下：
projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking 將其設為 "CLIENT" 可啟用用戶端追蹤功能。
gamSettings 包含網路代碼和串流 ID 的物件，格式如下： 
{
  "networkCode":"NETWORK_CODE",
  "streamId":"STREAM_ID"
}

回應 JSON

name VOD 工作階段的名稱，包含工作階段 ID。
playUri 拼接串流資訊清單的 URI，可載入至影片播放器進行播放。
SESSION_PLAYBACK_URI
adTracking 在要求主體中傳送至 API 的相同 adTracking 值。
vodConfig 在要求主體中傳送至 API 的相同 vodConfig 字串。
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/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

回應範例

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

收到回應後，您可以參照回應物件的 playUri 欄位中的 URI，播放已加入廣告的直播串流。

向 Ad Manager 要求廣告連播中繼資料

請向您在向 Ad Manager 註冊串流時收到的 metadata_url 發出 GET 要求。您必須先從播放 URI 收到已拼接的資訊清單，才能執行這個步驟。

您會收到描述串流廣告休息時間、廣告和廣告事件的 JSON 物件。

API 端點

GET: METADATA_URL
Host: dai.google.com

回應 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 METADATA_URL

JSON 回應範例

{
  "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
    },
    ...
  }
}

儲存這些值，以便與影片串流中的時間中繼資料事件建立關聯。

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