Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

準備用戶端，以進行廣告連播放送重新導向

本指南說明如何開發用戶端應用程式，透過 Pod 放送 API 和資訊清單操控器載入 HLS 或 DASH 直播串流。

必要條件

繼續操作前，請務必備妥下列項目：

使用 Pod serving redirect DAI 類型設定的直播活動自訂素材資源金鑰。如要取得這項金鑰，請按照下列步驟操作：
- 為動態廣告插播設定直播活動。
- 使用 SOAP API 用戶端程式庫，透過 LiveStreamEvent 物件呼叫 LiveStreamEventService.createLiveStreamEvents 方法，並將 dynamicAdInsertionType 屬性設為 POD_SERVING_REDIRECT 列舉值。如需所有用戶端程式庫，請參閱「用戶端程式庫和程式碼範例」。
判斷您的平台是否支援 Interactive Media Ads (IMA) SDK。建議使用 IMA SDK 提高收益。詳情請參閱「設定 IMA SDK 以使用 DAI」。

提出串流要求

使用者選取串流時，請執行下列操作：

向直播服務方法發出 POST 要求。詳情請參閱「方法： stream」。

以 application/x-www-form-urlencoded 或 application/json 格式傳遞指定廣告目標參數。這項要求會向 Google DAI 註冊串流工作階段。

以下範例會提出串流要求：

表單編碼

const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

JSON 編碼

const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

如果成功，您會看到類似以下的輸出內容：

{
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

在 JSON 回應中找出串流工作階段 ID，並儲存其他資料以供後續步驟使用。

重要事項： 如要讓應用程式正常運作，請直接使用回覆中提供的網址。請勿建構網址，因為路徑可能會變更。

投票廣告中繼資料

如要輪詢廣告中繼資料，請按照下列步驟操作：

從串流註冊回應中讀取 metadata_url 值。
向 metadata_url 端點發出初始 GET 要求。
- 省略 delta_token 查詢參數。這個程序可讓伺服器傳回串流的數位錄影機 (DVR) 倒帶時間範圍完整中繼資料。DVR 段落會顯示觀眾可倒轉及播放的廣播時間範圍。回覆內容包含 next_delta_token 欄位。
為節省頻寬，請儲存最近一次回應中的 next_delta_token 值。

在下一個要求中，將該值做為 delta_token 查詢參數傳送。伺服器只會傳回自產生權杖以來變更的中繼資料。請務必傳送您收到的最新權杖。請勿嘗試剖析、修改或建構權杖。詳情請參閱「方法：中繼資料」。

以下範例會擷取廣告中繼資料：

// Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

如果成功，您會收到 PodMetadata 回應。如果您提供 delta_token 參數，回應內容只會包含伺服器自產生權杖後新增或更新的廣告、廣告插斷和標記。回應也會包含新的 next_delta_token 值。如果廣告插播過時，回應也會包含 obsolete_ad_break_ids 清單，列出要從快取中移除的廣告插播。

{
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

儲存 tags 物件，並將更新合併至本機快取。如果存在 obsolete_ad_break_ids 參數，請從快取中移除這些廣告插播和相關聯的廣告與代碼。
使用 polling_frequency 值設定計時器，定期要求中繼資料。在每次輪詢中，將最近一次中繼資料回應傳回的 next_delta_token 值，做為 delta_token 查詢參數傳送。

將串流載入影片播放器

從註冊回應取得工作階段 ID 後，請將 ID 傳遞至資訊清單操控器，或建構資訊清單網址，將串流載入影片播放器。

如要傳遞工作階段 ID，請參閱資訊清單操控器說明文件。如果您開發資訊清單操控器，請參閱直播的資訊清單操控器。

以下範例會組裝資訊清單網址：

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

播放器準備就緒後，即可開始播放。

監聽廣告事件

檢查串流的容器格式，確認是否支援時間碼中繼資料：

使用傳輸串流 (TS) 容器的 HLS 串流會使用時間碼 ID3 標記，攜帶時間碼中繼資料。詳情請參閱「關於採用 HTTP 即時串流 (HLS) 的通用媒體應用格式」。
DASH 串流會使用 EventStream 元素，在資訊清單中指定事件。
如果片段包含酬載資料的事件訊息 (emsg) 方塊 (包括 ID3 標記)，DASH 串流會使用 InbandEventStream 元素。詳情請參閱「InbandEventStream」。
CMAF 串流 (包括 DASH 和 HLS) 會使用含有 ID3 標記的 emsg 方塊。

如要從串流擷取 ID3 標記，請參閱影片播放器的指南。詳情請參閱處理時間碼中繼資料指南

如要從 ID3 代碼擷取廣告事件 ID，請按照下列步驟操作：

使用 urn:google:dai:2018 或 https://aomedia.org/emsg/ID3 依 scheme_id_uri 篩選事件。

從 message_data 欄位擷取位元組陣列。

以下範例會將 emsg 資料解碼為 JSON：

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1022389921",
  ...
}

使用 TXXXgoogle_{ad_event_ID}: 格式篩選 ID3 標記：
```
TXXXgoogle_1022389921
```

顯示廣告事件資料

如要找出 TagSegment 物件，請按照下列步驟操作：

從「Poll ad metadata」(輪詢廣告中繼資料) 中擷取廣告中繼資料 tags 物件。tags 物件是 TagSegment 物件的陣列。
使用完整的廣告事件 ID 找出類型為 progress 的 TagSegment 物件。
使用廣告事件 ID 的前 17 個字元，找出其他類型的 TagSegment 物件。

由於用戶端應用程式會定期輪詢廣告中繼資料，因此影片播放器在串流中遇到 ID3 標記，到相關中繼資料可供使用之間，可能會發生延遲。如果用戶端應用程式在儲存的標記中找不到 ID3 標記，請將標記保留在佇列中，並在下一次中繼資料輪詢後重新處理標記。請將標記保留在佇列中，直到處理完成為止。
取得 TagSegment 後，請使用 ad_break_id 屬性做為鍵，在廣告中繼資料 ad_breaks 物件中尋找 AdBreak 物件。

以下範例會尋找 AdBreak 物件：
```
{
  "type":"mid",
  "duration":15,
  "ads":1
}
```
使用 TagSegment 和 AdBreak 資料，顯示廣告插播中廣告位置的相關資訊。例如：Ad 1 of 3。

傳送媒體驗證 Ping

針對每個廣告事件 (progress 類型除外)，傳送媒體驗證 Ping。Google DAI 會捨棄 progress 事件，因此頻繁傳送這些事件可能會影響應用程式效能。

如要產生廣告事件的完整媒體驗證網址，請完成下列步驟：

從串流回應中，將完整廣告事件 ID 附加至 media_verification_url 值。

使用完整網址發出 GET 要求：

// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

如果成功，您會收到 202 狀態碼回應。否則你會收到 404 錯誤代碼。

您可以使用串流播放活動監控器 (SAM)，檢查所有廣告事件的歷史記錄。詳情請參閱「監控及排解直播問題」。