DAI API 目前為 Beta 版,可能未在您的聯播網中推出。如需詳細資訊,請與您的客戶經理聯絡。我們建議採用 IMA SDK 的平台。

適用於直播的動態廣告插播 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 要求「LIVE」串流,請對串流端點發出 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
這個網址是追蹤播放事件的基本端點。
中繼資料網址
這個網址是用來輪詢即將串流事件的定期資訊。
工作階段更新網址
這個網址可用來更新在初始串流要求期間傳送的串流要求參數。請注意,此要求的參數會取代先前串流設定的所有參數。
輪詢頻率
向 DAI API 請求更新 AdAd 中繼資料的頻率。

2. 全新 AdBreak 中繼資料的意見調查

透過中繼資料網址,設定輪詢輪詢時間的新 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:使用者代理程式參數會以瀏覽器專屬值 (而非基礎平台) 的形式傳送。
  • rdididtypeis_lat:裝置 ID 未正確傳遞,因此限制了下列功能的功能:
    • 展示頻率上限
    • 廣告依序輪播
    • 目標對象區隔和指定目標

最佳做法

請注意,直播活動的中繼資料端點會根據對應 ID3 標記的前置字元。這樣做是為了避免使用中繼資料端點立即對所有驗證節點進行連線偵測 (ping)。

其他資源