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

Google DAI API 可讓您在不支援 IMA SDK 的環境中導入支援 Google DAI 的串流。建議您還是在支援 IMA SDK 的平台上使用 IMA。

建議您在下列平台上使用 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 要求更新版 AdBreak 中繼資料的頻率 (以秒為單位)。

2. 新的 AdBreak Metadata 意見調查

設定計時器，以使用中繼資料網址，以輪詢頻率輪詢新的 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 標記的前置字串。這是為了避免使用中繼資料端點立即連線偵測所有驗證節點。

其他資源