Pod Serving API 目前處於封閉測試階段。如要進一步瞭解 Pod 服務，或是想要導入 Pod Serving API，請與您的 Google 客戶經理聯絡。

本頁面由 Cloud Translation API 翻譯而成。

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

Google DAI 廣告連播放送 API 可讓您執行由 Google Ads 提供的伺服器端廣告插播，同時保留自己的影片拼接控制權。

本指南將說明如何與 Pod Serving API 互動，並透過 IMA DAI SDK 實現類似的功能。如對支援的功能有任何具體問題，請與您的 Google 客戶經理聯絡。

Pod Serving API 支援 HLS 或 MPEG-DASH 串流通訊協定中的廣告連播串流。本指南著重於 HLS 串流，並在特定步驟中強調 HLS 和 MPEG-DASH 之間的主要差異。

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

向 Ad Manager 提出串流註冊要求

向串流註冊端點發出 POST 要求。您會依序收到 JSON 回應，其中包含要傳送至資訊清單操控伺服器和相關 Pod 服務 API 端點的串流 ID。

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 物件。必填

回應 JSON

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

要求範例 (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 回應並儲存相關值。

向資訊清單操作工具要求串流資訊清單

每個資訊清單操控工具都有不同的要求和回應格式。請與操縱器供應商聯絡，瞭解他們的具體需求。如果您要實作自己的資訊清單操控工具，請參閱資訊清單操控工具指南，瞭解這個元件的相關規定。

一般來說，您需要將上述註冊端點傳回的串流 ID 傳遞至資訊清單操控器，讓資訊清單操控器建構與工作階段相關的資訊清單。除非資訊清單操作工具明確指出，否則資訊清單要求的回應內容會是包含內容和廣告的影片串流。

要求範例 (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

一組鍵/值組合，其中包含串流中顯示的所有廣告事件。鍵值是廣告事件 ID 的前 17 個字元，這些字元會顯示在串流的時間中繼資料中，如果是 progress 類型的事件，則為完整的廣告事件 ID。

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

ad 與 ads 物件中鍵相符的廣告 ID。

ad_break_id 與 ad_breaks 物件中的鍵相符的廣告插播 ID。

type

廣告事件類型。廣告事件類型如下：

`start`	在廣告開頭觸發。
`firstquartile`	在第一個四分之一結束時觸發。
`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 串流，這些會以模擬 ID3 2.3 標記的頻內 emsg 事件傳送。每個相關的 emsg 方塊都會包含 scheme_id_uri 值 (https://aomedia.org/emsg/ID3 或 https://developer.apple.com/streaming/emsg-id3)，以及以 ID3TXXXgoogle_ 開頭的 message_data 值。這個 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",
  ...
}

部分媒體播放器程式庫會自動呈現 emsg 事件，模擬 ID3 標記為原生 ID3 標記。在這種情況下，MP4 串流會呈現與 MPEG_TS 相同的 ID3 標記。

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

每個廣告事件 ID 可與步驟 4 中的 tags 物件中的鍵相符。比對這些值的程序分為兩個步驟：

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

如果找不到與完整廣告事件 ID 相符的項目，請檢查 tags 物件，找出與廣告事件 ID 前 17 個字元相符的鍵。擷取事件類型和相關的 ad 和 ad_break 物件。這應該會擷取所有類型 (除了 progress 以外) 的事件。
使用擷取的資訊更新播放器的 UI。舉例來說，當您收到 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

每次收到 progress 以外類型的廣告事件時，都必須傳送媒體驗證 ping 至 Ad Manager。

如要產生廣告事件的完整媒體驗證網址，請將完整廣告事件 ID 附加至串流註冊回應中的 media_verification_url 值。

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

要求範例 (cURL)

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

成功回應範例

HTTP/1.1 202 Accepted

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

向 Ad Manager 提出串流註冊要求

API 端點

路徑參數

JSON 內文參數

回應 JSON

要求範例 (cURL)

回應範例

向資訊清單操作工具要求串流資訊清單

要求範例 (cURL)

回應範例 (HLS)

播放串流

向 Ad Manager 要求廣告連播中繼資料

要求範例 (cURL)

回應範例

監聽廣告事件

ID3 標記範例

電子郵件訊息方塊範例

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

廣告事件 ID 範例

標記物件範例

傳送媒體驗證 ping

要求範例 (cURL)

成功回應範例

其他資源