管理動態廣告插播直播

如果環境不支援導入 IMA SDK，您可以使用 Google DAI API 導入啟用 Google DAI 的串流。建議您在支援 IMA SDK 的平台上繼續使用 IMA。

建議在下列平台上使用 DAI API：

  • Samsung 智慧型電視 (Tizen)
  • LG 電視
  • HbbTV
  • Xbox (JavaScript 應用程式)
  • KaiOS

這個 API 支援 IMA DAI SDK 提供的基本功能。如對相容性或支援功能有具體疑問，請洽詢 Google 客戶經理。

為 LIVE 串流實作 DAI API

DAI API 支援使用 HLS 和 DASH 通訊協定的線性 (LIVE) 串流。 本指南所述步驟適用於這兩種通訊協定。

如要將 API 整合到應用程式中，用於 LIVE 串流，請完成下列步驟：

1. 要求串流

如要透過 DAI API 要求直播，請對串流端點發出 POST 呼叫。JSON 回應包含串流資訊清單，以及相關聯的 DAI API 端點和值。

要求主體範例

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

回應主體範例

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

錯誤回應

如果發生錯誤，系統會傳回標準 HTTP 錯誤代碼，且不含 JSON 回應主體。

剖析 JSON 回應，並儲存下列值：

stream_id
這個值可用於識別傳回的串流。
stream_manifest
這個網址會傳送至媒體播放器，用於播放串流。
media_verification_url
這個網址是追蹤播放事件的基準端點。
metadata_url
這個網址用於輪詢即將舉行的串流活動相關資訊。
session_update_url
這個網址用於更新初始串流要求期間傳送的串流要求參數。請注意，這項要求的參數會取代先前串流的所有參數。
polling_frequency
向 DAI API 要求更新 AdBreak 中繼資料的頻率 (以秒為單位)。

2. 輪詢新的 AdBreak 中繼資料

使用中繼資料網址，依輪詢頻率設定計時器，輪詢新的 AdBreak 中繼資料。如未在串流回應中指定，建議間隔預設為 10 秒。

如要最佳化頻寬，請執行下列操作：

  1. 對 metadata_url 端點發出初始 GET 要求。
    • 省略 delta_token 查詢參數。這個程序可讓伺服器傳回串流的數位錄影機 (DVR) 倒帶時間範圍完整中繼資料。DVR 段落會顯示觀眾可倒轉及播放的廣播時間範圍。回應會包含 next_delta_token 物件欄位。
  2. 在用戶端儲存中繼資料。
  3. 使用最新回應傳回的 next_delta_token 值進行後續呼叫。每個回應都包含 next_delta_token 值。 請務必傳送您收到的最新值。
  4. 更新儲存的中繼資料，合併變更並移除過時的廣告插播。

請勿嘗試剖析、建構或修改差異符記。權杖格式可能會變更。儲存收到的權杖，並在下一個要求中傳回未變更的權杖。

初始要求範例

初始要求不採用任何查詢參數，並會傳回完整的中繼資料：

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

後續要求範例

後續的每個要求都會將前一個回應中的 next_delta_token 值做為 delta_token 參數傳遞。回覆內容包含下列項目：

  • 廣告
  • 廣告插播
  • 伺服器核發權杖後新增或更新的標記。
  • obsolete_ad_break_ids 要從儲存的中繼資料中移除的廣告插播清單

伺服器會省略未變更的廣告插播時間點。以下範例顯示後續輪詢，使用 delta 權杖僅擷取這些近期變更：

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

如果成功，您會看到類似以下的輸出內容：

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. 監聽 ID3 事件並追蹤播放事件

如要確認影片串流中是否發生特定事件，請按照下列步驟處理 ID3 事件：

  1. 將媒體事件儲存在佇列中，並儲存每個媒體 ID 及其時間戳記 (如果播放器顯示的話)。
  2. 在播放器每次更新時間時，或以設定的頻率 (建議為 500 毫秒)，比較事件時間戳記與播放頭，檢查媒體事件佇列中最近播放的事件。
  3. 確認媒體事件已播放後，請在儲存的廣告插播時間點代碼中查詢媒體 ID，檢查類型。請注意，儲存的標記只包含媒體 ID 的前置字元，因此無法完全相符。
  4. 由於影片播放器應用程式會定期輪詢中繼資料網址，因此影片播放器在串流中遇到 ID3 標記，到相關中繼資料可供使用之間，可能會發生延遲。如果儲存的標記中沒有 ID3 標記，請將標記保留在佇列中，並在下次輪詢中繼資料後重新處理標記。請將活動保留在佇列中，直到處理完成為止。
  5. 在後設資料中找到代碼後，請根據下一節列出的廣告事件類型，檢查代碼的 type 欄位。如要追蹤影片播放器是否正在播放廣告插播，請使用 type 欄位中值為 progress 的事件。請勿將這些事件傳送至媒體驗證端點。如為其他事件類型，請將媒體 ID 附加至媒體驗證端點，並發出 GET 要求來追蹤播放情形。
  6. 從佇列中移除媒體事件。

廣告事件類型

中繼資料 tags 物件中的每個標記都有下列其中一種事件類型：

事件類型 說明
start 在廣告開頭執行。
firstquartile 在廣告的第一個四分位數結束時執行。
midpoint 在廣告中間點放送。
thirdquartile 廣告播放至四分之三時觸發。
complete 在廣告結尾播放。
progress 在廣告插播期間定期執行，表示廣告插播正在播放。請勿將這些事件傳送至媒體驗證端點。

要求範例

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

回覆範例

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

您可以在串流活動監控器中驗證追蹤事件。

4. 更新直播工作階段參數

建立串流後，您可能需要調整工作階段參數。如要這麼做，請向工作階段更新網址提出要求。

要求主體範例

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

回應內文範例

Successful response would be to look for - HTTP/1.1 200

限制

如果在 WebView 中使用 API，則目標對象方面會受到下列限制：

  • UserAgent：使用者代理程式參數會以瀏覽器專屬值傳遞，而非基礎平台。
  • rdid, idtype, is_lat: 裝置 ID 未正確傳遞，因此下列功能受到限制：
    • 展示頻率上限
    • 依序輪播廣告
    • 目標對象區隔和指定目標

最佳做法

請注意，直播索引的中繼資料端點是根據對應 ID3 標記的前置字元而定。這是為了防止使用中繼資料端點立即 Ping 所有驗證節點而設計。

其他資源