VOD 串流的用戶端影片播放器應用程式

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: /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 內含內容來源 ID (cmsid)、影片 ID (vid) 和廣告指定目標參數的 JSON 物件。必填

回應 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 \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

回應範例

{
  "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。

每個值都是一個物件，其中包含下列參數：

ad 與 ads 物件中鍵相符的廣告 ID。
ad_break_id 與 ad_breaks 物件中鍵相符的廣告插播 ID。
type 廣告事件的類型。廣告事件類型如下：
start 在廣告開頭觸發。
firstquartile 在第一個四分位數的結束時觸發。
midpoint 在廣告一半時觸發。
thirdquartile 播放到四分之三的結束時觸發。
complete 在廣告結束時觸發。
progress 在整個廣告中定期觸發，以通知應用程式正在播放廣告插播。
ads 一組鍵/值組合，用來說明串流中顯示的所有廣告。這些鍵是與上述 tags 物件中找到的值相符的廣告 ID。每個值都是一個物件，其中包含下列參數：
ad_break_id 與 ad_breaks 物件中鍵相符的廣告插播 ID。
position 此廣告在廣告插播組合中的顯示位置 (以浮點秒為單位)。
duration 廣告的長度 (以浮點秒為單位)。
clickthrough_url 當使用者與此廣告互動時，所開啟的網址 (如果支援)。
ad_breaks 一組鍵/值組合，用於說明串流中顯示的所有廣告插播。 這些鍵是廣告插播 ID，會與上述 tags 和 ads 物件中的值相符。每個值都是一個物件，其中包含下列參數：
type 廣告插播的類型。廣告插播類型有 pre (片頭廣告)、mid (片中廣告) 和 post (片尾廣告)。
duration 廣告插播的時間長度 (以浮點秒為單位)。
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 物件的鍵。比對這些值的程序有兩個步驟：

  1. 查看 tags 物件，找出與完整廣告事件 ID 相符的鍵。如果找到相符項目，請擷取事件類型及其相關聯的 ad 和 ad_break 物件。這些事件應具有 progress 類型。

    如果找不到與完整廣告事件 ID 相符的項目，請檢查 tags 物件，找出與廣告事件 ID 前 17 個字元相符的鍵。擷取事件類型以及相關聯的 ad 和 ad_break 物件。這樣應會擷取類型不含 progress 以外的所有事件。

  2. 利用擷取到的資訊來更新玩家的使用者介面。舉例來說，當您收到 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 要求。如果驗證要求成功，您會收到狀態碼為 202 的 HTTP 回應。否則，您會收到 HTTP 錯誤代碼 404。

要求範例 (cURL)

curl https://{...}/media/google_5555555555123456789

成功回應範例

HTTP/1.1 202 Accepted

其他資源