直播活動的動態廣告插播 API

Google DAI API 可讓你在環境中導入支援 Google DAI 的串流 不支援導入 IMA SDK我們建議您仍使用 IMA SDK 支援 IMA SDK。

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

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

這個 API 支援 IMA DAI SDK 提供的基本功能。適用對象 有關相容性或支援功能的特定問題，請聯絡： 聯絡 Google 客戶經理。

為直播串流導入 DAI API

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

如要將 API 整合到您的應用程式以進行直播串流，請完成下列步驟 步驟：

1. 要求直播

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

要求主體範例

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

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

回應主體範例

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

錯誤回應

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

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

stream_id
這個值可用來識別傳回的串流。
stream_manifest
這個網址會傳送到您的媒體播放器以便串流播放。
media_verification_url
這個網址是追蹤播放事件的基礎端點。
metadata_url
這個網址是用來輪詢有關近期直播的定期資訊 事件。
session_update_url
這個網址是用來更新在初始階段傳送的串流要求參數 串流請求請注意，此請求的參數會取代所有參數 偵測到較早的串流
polling_frequency
這是指向 DAI API。

2. 針對新的 AdBreak 中繼資料進行意見調查

使用 中繼資料網址。如果未在串流回應中指定，則系統會採用預設的建議選項 間隔為 10 秒

要求主體範例

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/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/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "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
      },....
   }
}

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

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

  1. 將媒體事件儲存在佇列中，一併儲存各個媒體 ID 及其相關資料 時間戳記 (如果由播放器顯示)。
  2. 每次更新播放器時，或按指定頻率更新時 (建議採用) 500 毫秒)，按照以下方式查看媒體事件佇列，找出最近播放的事件： 比較事件時間戳記與播放頭
  3. 確認已播放的媒體事件時，透過查詢的方式檢查類型 所儲存廣告插播代碼中的媒體 ID。請注意，已儲存的代碼 只加入媒體 ID 的前置字元，因此無法完全相符。
  4. 使用「進度」事件來追蹤使用者是否在廣告插播中。 請勿將這些事件傳送至媒體驗證端點。其他活動 類型，將媒體 ID 附加至媒體驗證端點，然後建立 GET 要求追蹤播放。
  5. 將媒體事件從待播清單中移除。

要求主體範例

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

回應範例

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/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/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)。

其他資源