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

Google DAI Pod Serving API 可讓您執行採用技術的伺服器端廣告插播 ，並仍能掌控自行拼接的影片。

本指南說明如何與 Pod Serving API 互動，並達成 導入與 IMA DAI SDK 類似的功能若有 請與您的 Google 客戶經理聯絡。

Pod Serving API 支援 HLS 或 MPEG-DASH 中的 Pod 放送串流 串流通訊協定本指南著重於 HTTP 即時串流串流，並重點說明 HLS 和 MPEG-DASH 在特定步驟中的差異。

如要將 Pod Serving API 整合至應用程式，以便進行 VOD 串流作業，請完成 步驟如下：

向 Ad Manager 提出串流註冊請求

向串流註冊端點發出 POST 要求。您獲得了 JSON 回應，內含要傳送至資訊清單操控的串流 ID 和相關聯的 Pod Serving 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 JSON 物件，內含內容來源 ID (cmsid)、影片 ID (vid) 和 廣告指定目標 參數必填

回應 JSON

media_verification_url 連線偵測播放追蹤事件的基準網址。完成媒體驗證 產生網址的方法是將廣告事件 ID 附加至這個基本網址。
metadata_url 用於要求廣告連播中繼資料的網址。
stream_id 用於識別目前串流工作階段的字串。
valid_for 目前串流工作階段到期所剩的時間 dhms (天、小時、分鐘、秒) 格式。例如： 2h0m0.000s 表示時間長度為 2 小時。
valid_until 目前串流工作階段的到期時間，以 ISO 8601 格式表示 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm中的日期時間字串 格式。

要求範例 (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 回應並儲存相關值。

透過資訊清單操縱器要求串流資訊清單

每個資訊清單操縱器都有不同的要求和回應格式。聯絡 以便瞭解他們的具體需求。如果您是 實作自己的資訊清單操作工具，請詳閱資訊清單操縱器 指南，瞭解 必須滿足這項元件的需求

一般來說，您需要傳遞 新增到資訊清單操作器，以便建構 工作階段專屬資訊清單除非資訊清單明確指出 資訊清單要求的回應是含有 內容與廣告

要求範例 (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 一組鍵/值組合，其中包含顯示在 串流。鍵是廣告事件的前 17 個字元 出現在串流計時中繼資料，或如為事件，則會出現這個 ID progress 類型，完整的廣告事件 ID。

每個值都是一個含有下列參數的物件：

ad 與 ads 物件中鍵相符的廣告 ID。
ad_break_id 與 ad_breaks 中鍵相符的廣告插播 ID 物件。
type 廣告事件的類型。廣告事件類型如下：
start 廣告開頭觸發。
firstquartile 播放到 25% 結束時觸發。
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 串流，則會以頻內 emsg 事件的形式傳送，並模擬 ID3 v2.3 標記內。每個相關的電子郵件方塊都有一個 scheme_id_uri 值： https://aomedia.org/emsg/ID3 或 https://developer.apple.com/streaming/emsg-id3 和 message_data 值 開頭為 ID3TXXXgoogle_。這個 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",
  ...
}

部分媒體播放器程式庫會自動顯示模擬 ID3 的電子訊息事件 指定為原生 ID3 代碼在這種情況下，MP4 串流會顯示相同的 ID3 標記 以及 MPEG_TS 格式。

更新用戶端影片播放器應用程式的使用者介面

每個廣告事件 ID 都可以與步驟 4 中 tags 物件中的鍵進行比對。 比對這些值有兩個步驟：

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

    如果找不到完整的廣告事件 ID 相符，請查看 tags 同一個鍵的物件。 擷取事件類型與相關聯的 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)

每次廣告事件都必須傳送媒體驗證連線偵測 (ping) 至 Ad Manager 接收類型不是 progress 的情況。

如要產生廣告事件的完整媒體驗證網址，請在網址後方附加完整的 將廣告事件 ID 對應到串流登錄中的 media_verification_url 值 回應。

使用完整網址發出 GET 要求。如果驗證要求 成功，您會收到狀態碼為 202 的 HTTP 回應。 否則，您會收到 HTTP 錯誤代碼 404。

要求範例 (cURL)

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

成功的回應範例

HTTP/1.1 202 Accepted

其他資源