動態廣告插播廣告連播放送 Live API

動態廣告插播 API 可讓您要求及追蹤 DAI 直播。

服務：dai.google.com

所有 URI 皆為 https://dai.google.com 的相對路徑。

方法：串流

HTTP 要求

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

路徑參數

要求主體

要求主體的類型為 application/x-www-form-urlencoded，並包含下列參數：

回應主體

如果成功，回應主體會包含新的 Stream 物件。

Open Measurement

DAI API 會在 Verifications 欄位中提供 Open Measurement 驗證資訊。這個欄位包含一或多個 Verification 元素，該元素會列出執行第三方評估程式碼所需的資源和中繼資料，以確認廣告素材播放。系統僅支援 JavaScriptResource。詳情請參閱 IAB Tech Lab 和 VAST 4.1 規格。

方法：廣告連播區隔

HTTP 要求

GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

路徑參數

查詢參數

註釋

1. 初始化區隔不需要使用 sd。↩
2. 如果事件已啟用無時間長度的廣告插播，則不需要 pd。↩

範例

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

回應主體

如果成功，回應主體會是可播放的串流片段，且符合要求中指定的格式和參數。

方法：HLS Pod 資訊清單

擷取直播的 HLS 廣告連播資訊清單，讓用戶端影片播放器載入及播放。

HTTP 要求

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

路徑參數

查詢參數

回應主體

如果成功，回應主體會是 HTTP 即時串流多變化版本播放清單。

方法：DASH 廣告連播資訊清單

擷取直播的 MPEG-DASH 廣告連播資訊清單，讓用戶端影片播放器載入及播放。

HTTP 要求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

路徑參數

查詢參數

回應主體

如果成功，回應主體會是 MPEG-DASH mpd 播放清單。

方法：DASH 小組週期範本

HTTP 要求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

路徑參數

查詢參數

回應主體

如果成功，回應主體會包含新的 PodTemplateResponse 物件。

方法：媒體驗證

在播放期間遇到廣告媒體 ID 後，請立即使用從上述 stream 端點取得的 media_verification_url 提出要求。對於伺服器端信標串流 (伺服器會啟動媒體驗證)，這些要求並非必要。

向 media verification 端點發出的要求皆為冪等。

HTTP 要求

GET https://{media-verification-url}/{ad-media-id}

回應主體

media verification 會傳回下列回應：

• HTTP/1.1 204 No Content：如果媒體驗證成功且已傳送所有 Ping，則會傳回此值。
• 如果要求因網址格式或過期而無法驗證媒體，則為 HTTP/1.1 404 Not Found。
• HTTP/1.1 404 Not Found。
• HTTP/1.1 409 Conflict：如果其他要求目前正在傳送連線偵測 (ping)。

廣告媒體 ID

廣告媒體 ID 會在獨立的媒體資料音軌中編碼，例如 HLS 傳輸串流的時間控管媒體資料，或 MP4 檔案的 emsg。廣告媒體 ID 一律以字串 google_ 開頭。

在提出每項廣告驗證要求前，應將結構描述項目的完整文字內容附加至廣告驗證網址。

方法：中繼資料

metadata_url 中的中繼資料端點會傳回用於建構廣告 UI 的資訊。中繼資料端點不適用於伺服器端信標串流，因為在這種情況下，伺服器負責啟動廣告媒體驗證。

HTTP 要求

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

回應主體

如果成功，回應會傳回 PodMetadata 例項。

剖析中繼資料

中繼資料包含三個獨立部分：tags、ads 和廣告 breaks。資料的進入點是 tags 部分。接著，請逐一檢查標記，找出名稱為影片串流中廣告媒體 ID前置詞的首個項目。舉例來說，您可能會看到類似以下的廣告媒體 ID：

google_1234567890

然後找出名為 google_12345 的標記物件。在這種情況下，它會與廣告媒體 ID 相符。找到正確的廣告媒體前置字元物件後，您可以查詢廣告 ID、廣告插播 ID 和事件類型。接著，系統會使用廣告 ID 為 ads 物件建立索引，並使用廣告插播 ID 為 breaks 物件建立索引。

回應資料

串流

{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}

PodMetadata

{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}

TagSegment

{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}

AdBreak

{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}

廣告

{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}

PodTemplateResponse

{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}

圖示

{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}

ClickData

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Wrapper

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

驗證

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

TrackingEvent

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

夥伴

{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}

InteractiveFile

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}