每次開始播放直播時,您都可以使用 Video Stitcher API 建立直播工作階段,在廣告插播期間動態併接 Google Ad Manager 放送的廣告。回應包含播放網址和直播工作階段的設定。
本頁說明如何建立及管理透過 Google Ad Manager 啟用的直播工作階段。如要瞭解不使用 Google Ad Manager 的直播工作階段,請參閱「管理直播工作階段」。
事前準備
- 建立即時設定。如要與 Google Ad Manager 整合,請確保已設定
gamLiveConfig
物件。 - 如果您要指定候選影片組合,請務必在註冊的候選影片組合中設定
gamSlate
物件。
建立直播工作階段
您可以透過 IMA SDK (呼叫 Video Stitcher API) 或直接使用 Video Stitcher API 建立直播工作階段。
使用 IMA SDK
如果您與 IMA SDK 整合,IMA SDK 會建立直播工作階段。
function requestVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest(); streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY'; streamManager.requestStream(streamRequest); }
您可以為每個工作階段設定或覆寫下列選用參數:
manifestOptions
:指定要在縫合影片資訊清單中產生的影片轉譯版本,以及轉譯版本的順序;請參閱資訊清單選項說明文件adTracking
:選取用戶端廣告追蹤或伺服器端廣告追蹤targetingParameters
:Google Ad Manager 廣告代碼,可包含可依工作階段更新的指定目標參數;請參閱如何使用 IMA SDK 設定指定目標參數
請參閱下一節,瞭解如何使用 IMA SDK 設定這些參數。
選用參數和覆寫
您可以為每個工作階段設定選用參數,例如 manifestOptions
欄位。
這個欄位不適用於即時設定。您也可以覆寫特定工作階段的即時設定中設定的參數。
舉例來說,如果將即時設定中的預設 adTracking
設為 SERVER
,您可以將該值覆寫為 CLIENT
,並透過設定 videoStitcherSessionOptions
JSON 物件欄位,在 IMA SDK 中設定 manifestOptions
欄位。
function requestVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest(); streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY'; streamRequest.videoStitcherSessionOptions = { adTracking: 'CLIENT', 'manifestOptions': { 'includeRenditions': [ { 'bitrateBps': 150000, 'codecs': 'hvc1.1.4.L126.B0' }, { 'bitrateBps': 440000, 'codecs': 'hvc1.1.4.L126.B0' }, ], 'bitrateOrder': 'descending' } }; streamRequest.adTagParameters = { "key1": "value1", "key2": "value2", }; streamManager.requestStream(streamRequest); }
詳情請參閱「新增串流工作階段選項」。
直接使用 API
如要直接使用 API 建立直播工作階段,請使用 projects.locations.liveSessions.create
方法。
JSON 內文中只有 liveConfig
欄位為必填。您可以為每個即時工作階段設定或覆寫下列選用參數 (如下列 REST 範例所示):
manifestOptions
:指定要在縫合影片資訊清單中產生的影片轉譯版本,以及轉譯版本的順序;請參閱資訊清單選項說明文件adTracking
:選取用戶端廣告追蹤或伺服器端廣告追蹤;這會覆寫工作階段即時設定中的值targetingParameters
:Google Ad Manager 廣告代碼可包含可依工作階段更新的指定目標參數;在這個欄位中提供對應 (例如,如要將[my_key]
巨集替換為my_value
字串,請參閱 REST 範例)
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", "manifestOptions": { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" } ], "bitrateOrder": "DESCENDING" }, "gamSettings": { "streamId": "STREAM_ID" }, "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", "adTracking": "SERVER" }
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
,工作階段就會過期。
如果您要代表顧客裝置產生工作階段,可以使用 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 位址不符。
取得工作階段
如要取得即時工作階段,請使用 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", "manifestOptions": { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" } ], "bitrateOrder": "DESCENDING" }, "gamSettings": { "streamId": "STREAM_ID", "targetingParameters": { "my_key": "my_value" } }, "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID", "adTracking": "SERVER" }
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://dai.google.com/.../ad-1/seg-1.ts
#EXTINF:5.000
https://dai.google.com/.../ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://dai.google.com/.../ad-2/seg-1.ts
#EXTINF:5.000
https://dai.google.com/.../ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts
檢查透過 Google Ad Manager 啟用的即時工作階段
如要查看工作階段的廣告代碼詳細資料,請使用 Ad Manager 中的串流播放活動監控器,查看廣告請求的詳細資料。