每次開始播放直播時,您都可以使用 Video Stitcher API 建立即時工作階段,在廣告時段動態拼接廣告。回應包含播放網址和直播工作階段的設定。
本頁面說明如何建立及管理未透過 Google Ad Manager 啟用的直播工作階段。如要進一步瞭解這類直播工作階段,請參閱「管理透過 Google Ad Manager 啟用的直播工作階段」。
事前準備
建立直播工作階段
如要建立直播工作階段,請使用 projects.locations.liveSessions.create
方法。
建立直播工作階段時,下列欄位為選填:
adTagMacros
:廣告代碼巨集替換的鍵/值組合清單;請參閱「廣告代碼巨集」一節manifestOptions
:指定要在縫合影片資訊清單中產生的影片轉譯版本,以及轉譯版本的順序;請參閱資訊清單選項說明文件
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:位於「IAM 設定」頁面「專案編號」欄位的 Google Cloud 專案編號LOCATION
:建立工作階段的位置;請使用其中一個支援的區域顯示地區us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
LIVE_CONFIG_ID
:使用者定義的即時設定 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", "playUri": "PLAY_URI", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", }
C#
在試用這個範例之前,請先按照C#使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API C# API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
在試用這個範例之前,請先按照Go使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Go API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
在試用這個範例之前,請先按照Java使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Java API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
在試用這個範例之前,請先按照Node.js使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Node.js API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
在試用這個範例之前,請先按照PHP使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API PHP API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
在試用這個範例之前,請先按照Python使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Python API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
在試用這個範例之前,請先按照Ruby使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Ruby API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
回應是即時工作階段物件。playUri
是用戶端裝置用來播放這個直播工作階段的廣告縫合串流的網址。
Video Stitcher API 會為每個要求產生專屬工作階段 ID。如果過去 5 分鐘內未要求 playUri
,工作階段就會過期。
廣告必須先經過編碼,才能縫合到直播工作階段。為廣告縫合影片建立工作階段時,Video Stitcher API 會判斷廣告是否已從先前的工作階段編碼。API 只會尋找與 Google Cloud 專案相關聯的會期所建立的編碼廣告。如要進一步瞭解這項程序,請參閱總覽。
如果您要代表顧客裝置產生工作階段,可以使用 HTTP 標頭設定下列參數:
參數 | HTTP 標頭 |
---|---|
CLIENT_IP |
x-forwarded-for |
REFERRER_URL |
referer |
USER_AGENT |
user-agent |
您可以在上述 curl
要求中加入下列標頭:
-H "x-forwarded-for: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
如果未提供 x-forwarded-for
標頭,Video Stitcher API 會在廣告中繼資料要求中使用用戶端 IP 位址。請注意,如果工作階段是代表顧客裝置產生,用戶端的 IP 位址可能與顧客裝置的 IP 位址不符。
廣告代碼巨集
廣告代碼可以包含巨集,因此每個工作階段可能會產生不同的廣告代碼。廣告代碼中的巨集會以方括號表示,如下例所示:
AD_TAG_URI¯o=[my-key]
adTagUri
是在即時設定中定義。
如要替換廣告代碼巨集中的值,請在 adTagMacros
欄位中提供對應。舉例來說,如要將 [my-key]
巨集替換為 my-value
字串,您需要提供下列項目:
{ ... "adTagMacros": { "my-key": "my-value" }, ... }
Video Stitcher API 要求廣告中繼資料時,會使用下列廣告代碼:
AD_TAG_URI¯o=my-value
取得工作階段
如要取得即時工作階段,請使用 projects.locations.liveSessions.get
方法。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:位於「IAM 設定」頁面「專案編號」欄位的 Google Cloud 專案編號LOCATION
:建立工作階段的位置;請使用其中一個支援的區域顯示地區us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
:即時會議的 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", "playUri": "ad-stitched-live-stream-uri", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", }
C#
在試用這個範例之前,請先按照C#使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API C# API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
在試用這個範例之前,請先按照Go使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Go API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
在試用這個範例之前,請先按照Java使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Java API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
在試用這個範例之前,請先按照Node.js使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Node.js API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
在試用這個範例之前,請先按照PHP使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API PHP API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
在試用這個範例之前,請先按照Python使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Python API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
在試用這個範例之前,請先按照Ruby使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Ruby API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
已插入廣告的播放清單範例
以下是廣告縫合前的來源直播播放清單範例:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:32:00Z",DURATION=60,SCTE35-OUT=0xF...
#EXTINF:10.010
segment_00007.ts
#EXTINF:10.010
segment_00008.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:39:20Z",SCTE35-IN=0xF...
#EXTINF:10.010
segment_00009.ts
以下顯示廣告縫合後的來源直播播放清單範例:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts
處理用戶端廣告追蹤
啟用用戶端廣告追蹤功能後,播放器會負責觸發廣告追蹤事件。Video Stitcher API 提供的廣告中繼資料包括廣告追蹤和隨播廣告資訊。Video Stitcher API 會從廣告代碼回應中剖析這項資訊。
從資訊清單取得 HTTP 即時串流廣告中繼資料 URI
在 HLS 轉譯資訊清單中,AdMetadataURI
會編碼為 #EXT-X-DATERANGE
標記的 X-VAST-META
屬性。#EXT-X-DATERANGE
代碼位於每個廣告的第一個縫合片段之前。
以下是 HLS 時間碼中繼資料標記的範例:
#EXT-X-DATERANGE:ID="id123",START-DATE=2014-03-05T11:15:00Z,DURATION=15,X-VAST-META="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"
X-VAST-META
屬性的值是經過 base64 編碼的 JSON 字串。解碼後,您可以從 JSON 中擷取 AdMetadataURI
。
以下範例顯示解碼後的 X-VAST-META
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
從資訊清單取得 DASH 廣告中繼資料 URI
在 DASH 資訊清單中,每個縫合的廣告時段都包含一個 VAST 廣告,且廣告中繼資料 URI 可從 EventStream
標記中擷取。AdMetadataURI
會編碼在 Event
元素的 messageData
屬性中。Event
是標記 EventStream
內的元素,且 schemeIdUri
為 urn:videostitcher:admetadata:202008
。
以下是 DASH 事件串流代碼範例:
<EventStream schemeIdUri="urn:videostitcher:admetadata:202008" timescale="1000">
<Event duration="5000" messageData="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"></Event>
</EventStream>
使用 base64 將 messageData
解碼為 JSON。
以下範例顯示解碼後的 messageData
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
擷取及處理廣告追蹤事件
取得 AdMetadataURI
後,您就可以擷取廣告中繼資料。
以下範例顯示廣告中繼資料:
{
"activityEvents": [
{
"type": "PAUSE",
"uri": "https://example.com/pause"
}
],
"progressiveEvents": [
{
"timeOffset": "0s",
"events": [
{
"type": "IMPRESSION",
"uri": "https://example.com/impression"
},
{
"type": "START",
"uri": "https://example.com/start"
}
]
},
{
"timeOffset": "2.500s",
"events": [
{
"type": "FIRST_QUARTILE",
"uri": "https://example.com/firstquartile"
}
]
}
],
"adDuration": "10s"
}
在上述範例中,用戶端應執行下列操作:
- 在廣告影片開始時要求
https://example.com/start
- 在廣告影片開始時要求
https://example.com/impression
- 每當觀眾暫停廣告影片時,就發出
https://example.com/pause
請求 - 要求廣告影片播放 2.5 秒
https://example.com/firstQuartile
檢查即時工作階段
本節說明如何檢查直播工作階段,以及特定直播工作階段的廣告代碼詳細資料。詳情請參閱 REST 說明文件。
Video Stitcher API 會將要求傳送至即時工作階段要求主體中廣告代碼指定的廣告供應商。這些要求的請求和回應中繼資料會儲存 14 天,您可以在檢查即時工作階段時查看。
Video Stitcher API 會使用下列項目組成廣告代碼詳細資料:
- 指定廣告插播中要求的廣告代碼網址 (或預設廣告代碼,如果未指定任何代碼)
- 直播工作階段要求中設定的廣告代碼巨集
- 其他使用者中繼資料
這項資訊連同回應的主體和中繼資料,可深入瞭解 Video Stitcher API 的行為。
列出廣告代碼詳細資料
如要列出直播工作階段的廣告代碼詳細資料,請使用 projects.locations.liveSessions.liveAdTagDetails.list
方法。
請參考先前建立的直播課程的回應 (部分欄位已省略):
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", ... }
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:位於「IAM 設定」頁面「專案編號」欄位的 Google Cloud 專案編號LOCATION
:工作階段的位置,請使用支援的區域顯示地區us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
:即時會議的 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "liveAdTagDetails" : [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] } ] }
複製傳回的 LIVE_AD_TAG_DETAILS_ID
。您需要這個 ID 才能取得單一廣告代碼的詳細資料。
C#
在試用這個範例之前,請先按照C#使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API C# API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
在試用這個範例之前,請先按照Go使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Go API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
在試用這個範例之前,請先按照Java使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Java API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
在試用這個範例之前,請先按照Node.js使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Node.js API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
在試用這個範例之前,請先按照PHP使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API PHP API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
在試用這個範例之前,請先按照Python使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Python API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
在試用這個範例之前,請先按照Ruby使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Ruby API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
取得廣告代碼詳細資料
如要在直播工作階段中取得單一廣告代碼的詳細資料,請使用 projects.locations.liveSessions.liveAdTagDetails.get
方法。
以下範例說明如何使用先前要求傳回的廣告代碼詳細資料名稱,查看直播工作階段的單一廣告代碼詳細資料:
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:位於「IAM 設定」頁面「專案編號」欄位的 Google Cloud 專案編號LOCATION
:工作階段的位置,請使用支援的區域顯示地區us-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
:即時會議的 IDLIVE_AD_TAG_DETAILS_ID
:即時廣告代碼詳細資料的 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] }
C#
在試用這個範例之前,請先按照C#使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API C# API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
在試用這個範例之前,請先按照Go使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Go API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
在試用這個範例之前,請先按照Java使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Java API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
在試用這個範例之前,請先按照Node.js使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Node.js API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
在試用這個範例之前,請先按照PHP使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API PHP API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
在試用這個範例之前,請先按照Python使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Python API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
在試用這個範例之前,請先按照Ruby使用用戶端程式庫的 Video Stitcher API 快速入門中的設定說明操作。 詳情請參閱 Video Stitcher API Ruby API 參考說明文件。
如要向 Video Stitcher API 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。