總覽
Web Receiver SDK 原生支援廣告插播和隨播廣告
特定媒體串流中的各個事件它提供的 API 可設定廣告排序、廣告來源
以及廣告插播的行為和相關聯的廣告插播片段在本指南中,
Break
敬上
是指包含一或多則廣告/串場廣告的播放間隔,
每則廣告或串場廣告稱為
BreakClip
。
這些廣告插播時間點與載入中或播放的媒體相關聯。
廣告類型
Web Receiver SDK 支援用戶端廣告插播 (CSAI) 和伺服器 拼接式廣告插播 (SSAI)。客戶拼接廣告可以是由 或從 VAST 和 VMAP 範本檔案擷取的應用程式。 「伺服器拼接」廣告必須在載入內容之前手動指定, 內嵌廣告,或在內容播放期間以動態方式播放內嵌式已展開的廣告 廣告。下文將詳細說明每一種廣告類型的導入作業。
手動與客戶拼接
手動由客戶拼接的廣告插播時間點是整合的廣告插播類型
用戶端,且是由應用程式手動指定
SDK API。這種廣告類型不會嵌入主要內容的串流中。
BreakClip
必須提供
contentId
這個網址會指向廣告素材
contentType
描述廣告素材的格式
title
。
Break
必須具備
isEmbedded
和
expanded
設為預設值 false
。
position
敬上
可設為片頭、片中或片尾的廣告插播時間點 (詳情請參閱
分頁定位一節)。準備
Web Receiver SDK 會產生另一個播放器執行個體來載入廣告
並播放廣告內容這些廣告插播需要 stitched timeline
,且必須為
以靜態方式新增 (詳情請參閱
插入廣告部分)。以下範例顯示一個
手動導入客戶自行拼接廣告的方式如下:
// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';
// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;
// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.
VAST
Web Receiver SDK 支援新增 IAB 標準 VAST (影片廣告放送) 範本) 廣告。提供這個屬性後,系統會剖析 XML 範本,以產生 進入廣告插播時間點時,加入後續的「用戶端拼接」廣告插播片段。
如要建立 VAST 廣告,接收端應用程式必須建立
VastAdsRequest
敬上
並在 BreakClip
中指定
vastAdsRequest
資源。VastAdsRequest
物件必須具備 adsResponse
(
XML 範本本身的字串表示法) 或 adTagUrl
(網址)
(代管 XML 範本) 定義的屬性。如果已指定網址,則
SDK 會負責擷取範本封裝 Break
後
客戶拼接廣告的慣例。這類廣告可以與
手動進行客戶拼接,或是在
同樣的內容下方範例說明 VAST
廣告:
// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'
// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;
// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.
當輸入包含 VAST BreakClip
的 Break
時,網路接收端
SDK 會選擇性擷取,然後剖析範本。剖析時
會產生新的 BreakClip
,並填入從中擷取而來的值
範本,例如 contentId
、contentType
、title
、duration
whenSkippable
和 clickThroughUrl
。產生的廣告插播片段的 id
為
設為 GENERATED:N
,其中 N
是整數,每次新值會遞增 1
於 0
開始建立的 VAST 廣告插播片段。系統會將產生的廣告新增至
BreakClip
陣列。目前 Break
中,每個 VAST 廣告插播片段的 id
是
然後替換為對應產生的廣告插播片段 id
。文字片段
下文將說明
MEDIA_STATUS
敬上
廣告訊息。
Break
和 BreakClip
資訊,使您再進入 VAST 廣告。
"breaks": [
{
"id": "break_postroll_vast",
"breakClipIds": [
"bc_vast"
],
"position": 0,
"isWatched": false
}
],
"breakClips": [
{
"id": "bc_vast"
}
]
透過 VAST 廣告進入廣告插播時間點後,Break
和 BreakClip
資訊。
"breaks": [
{
"id": "break_postroll_vast",
"breakClipIds": [
"GENERATED:0"
],
"position": 0,
"isWatched": true
}
],
"breakClips": [
{
"id": "bc_vast"
},
{
"id": "GENERATED:0",
"contentId": "https://example.com/break-clip-1.mpd",
"contentType": "application/dash+xml",
"title": "Ad Title Extracted from Template",
"duration": 10,
"whenSkippable": 5,
"clickThroughUrl": "https://example.com/ad-target"
}
]
VMAP
Web Receiver SDK 支援 IAB VMAP (多影片廣告播放清單)
標準。提供 VMAP 時,Web 接收器 SDK 會剖析 VMAP
回應並針對任何 <AdBreak>
產生用戶端拼接的 Break
物件
回應中的條目還會使用以下指令產生適當的 BreakClips
:
每個 VMAP 中提供的每個 <AdSource>
項目都有 vastAdsRequest
物件。目的地:
啟用 VMAP 以便在內容中插入廣告。應用程式必須建立
VastAdsRequest
敬上
物件並指派給該物件
vmapAdsRequest
。
的
MediaInformation
的
LoadRequestData
。
這類廣告必須靜態插入 (詳情請參閱
廣告插入部分)。以下簡要說明
建立 VMAP 要求
// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'
// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;
嵌入
內嵌廣告插播是一種在伺服器端拼接的廣告插播類型
並插入主要內容的訊息串中。Break
的時間長度會減去
與主要內容時間長度的間隔值相差不遠。
BreakClip
必須提供
duration
廣告素材的大小
title
。
Break
必須具備
isEmbedded
已設為 true
和
expanded
已設為 false
。
position
敬上
可設為片頭或片中廣告插播時間點。片尾的廣告插播時間點
支援的確切正值 position
值。詳情請參閱
分段定位一節。觸發廣告的使用者
播放後,Web Receiver SDK 會以廣告區隔的形式繼續播放串流
嵌入其中的內容這個廣告類型沒有其他載入機制。
播放頭位於
中斷時間範圍。這些休息時間需要embedded timeline
,且必須新增
靜態 (詳情請參閱廣告插播一節)。
下方範例顯示 embedded
廣告的基本導入方式。
// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;
// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.
嵌入已展開
內嵌展開廣告插播是一種拼接伺服器的廣告插播類型
並顯示在主要內容的訊息串中納入 Break
的時間
決定媒體時間。
BreakClip
必須提供
duration
廣告素材的大小
title
。
Break
必須具備
isEmbedded
已設為 true
和
expanded
已設為 true
。
position
敬上
可設為片頭或片中廣告插播時間點。片尾的廣告插播時間點
支援的值為正 position
值。詳情請參閱
分段定位一節。觸發廣告的使用者
播放後,Web Receiver SDK 會以廣告區隔的形式繼續播放串流
嵌入其中的內容這個廣告類型沒有其他載入機制。
播放頭位於
中斷時間範圍。這些休息時間需要 embedded timeline
,且可新增
「靜態」或「動態」參數 (詳情請參閱
插入廣告部分)。以下範例顯示一個
導入 embedded expanded
廣告:
// Create the BreakClip.
let clipEmbeddedExpanded =
new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;
// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;
播放器時間軸類型
建立播放器例項時,Web Receiver SDK 會選取時間軸類型來
支援在內容播放期間播放廣告。每個時間軸都會啟用特定廣告
要新增的廣告插播類型時間軸類型取決於
廣告類型
MediaInformation
敬上
的
LoadRequestData
。
如果出現內嵌廣告插播,系統會選取 embedded
時間軸。如果
設有用戶端拼接廣告插播,並選取「stitched
」時間軸。
如果沒有顯示廣告,SDK 會預設使用 embedded
時間軸上。選取時間軸後,就不能變更目前設定的時間軸
媒體項目。下表提供每個時間軸的詳細說明。
時間軸類型 | 說明 |
---|---|
內嵌時間軸 | 表示支援廣告的媒體時間 嵌入主要內容中 (內嵌和內嵌式展開廣告插播)。 如果有未展開的廣告插播,時間長度 就會從 內容。另一方面,如果展開廣告 則系統會將其時間視為 部分主要內容。 |
拼接時間軸 | 表示支援廣告的媒體時間 來源為外部媒體檔案 (手動用戶端拼接、VAST 和 VMAP 廣告插播時間點)。新增時,廣告插播的時間長度為 並未納入主要內容的時間長度。 |
下方圖 1 至 3 說明部分內容包含各種廣告類型及 以及個別時間軸值內容設有片頭廣告插播時間點 包含兩個廣告插播片段,以及片中和片尾這兩種廣告插播時間點 一個廣告插播片段從內容開始播放以來的實際時間。 主要內容的媒體時間,以及廣告插播目前的時間 播放中斷影片時,會在每個圖形下方對齊。
分隔位置設定
Web Receiver SDK 可讓開發人員指定廣告插播時間點
放置在
position
敬上
Break
屬性。這個值會對應至主要內容的媒體時間
以及建立 pre-roll
、mid-roll
和 post-roll
廣告插播時間點。
定義如下:
分隔位置 | 說明 |
---|---|
片頭廣告 | 在主要內容播放前放送的廣告插播。這是
以將 breakPosition 設為 0 來表示 |
片中廣告 | 在內容中播放的廣告時段。就代表
將 breakPosition 設為中斷點的時間
開頭大於主要內容的開頭,且
休息的結束時間早於主要內容的結尾
讓應用程式從可以最快做出回應的位置
回應使用者要求 |
片尾廣告 | 在主要內容結束後播放的廣告時段。這是
以將 的 breakPosition 設為 -1
拼接時間軸。適用於內嵌式
時程breakPosition
應設為主要內容時間長度,減去
做為廣告插播的時間長度不支援直播內容。 |
互通性矩陣
為方便您快速參考,表 1 列出了各種廣告類型 以及廣告相關功能的相容性
功能支援 | 手動客戶拼接廣告 | VAST | VMAP | 內嵌廣告 | 嵌入式展開廣告 |
---|---|---|---|---|---|
相容於 | VAST | 手動與客戶拼接 | 不適用 | 嵌入已展開 | 嵌入 |
年表 | 有縫線 | 有縫線 | 有縫線 | 嵌入 | 嵌入 |
插入廣告 | 靜態 | 靜態 | 靜態 | 靜態 | 靜態、動態 |
移除廣告 | |||||
片頭廣告 | |||||
片中廣告 | |||||
影片後插播廣告 | |||||
略過廣告 | |||||
休息跳轉攔截器 | |||||
廣告插播載入攔截器 |
活動
當發生按鍵中斷事件時,cast SDK 會分派類型的事件
BreaksEvent
。
接收器應用程式可以使用 PlayerManager
訂閱
addEventListener
也能使用 Google Cloud CLI 或
Compute Engine API
這些事件可用於分析和廣告播放。採用 VMAP 時 (影片多重廣告播放清單) 和 VAST (影片廣告放送範本) 廣告 ,回應中提供的任何標準追蹤事件都會自動 自動調度 Pod 資源
事件類型列於表 2 及相關詳細說明 觸發時。
中斷活動 | 說明 |
---|---|
BREAK_STARTED |
主要內容的目前媒體時間等於
未觀看的休息時間:position 。 |
BREAK_CLIP_LOADING |
僅在拼接時間軸廣告插播片段開始載入時觸發。 |
BREAK_CLIP_STARTED |
廣告插播片段開始播放時觸發。 |
BREAK_CLIP_ENDED |
廣告插播片段結束時觸發。
endedReason
系統會在下列情況下填入值:
|
BREAK_ENDED |
廣告插播中的最後一個休息片段結束時觸發。 |
插入廣告
cast SDK 可讓應用程式在不同時間點插入及移除廣告
投放工作階段。廣告插播分為兩種:靜態和動態。
使用靜態插入功能時,您必須在
LoadRequestData
敬上
就能先行顯示動態廣告插播功能會使用
BreakManager
敬上
addBreak
這個 API 可在已載入的內容中插入廣告插播。各種插入項目
方法與特定廣告類型相容。相容性
請參閱互通性矩陣。
靜態廣告插播
靜態廣告插播的特徵是先提供相關廣告中繼資料
建立播放器這項資訊是在
MediaInformation
敬上
LoadRequestData
的存取權。舉例來說,您可以在已連線的寄件者的
也可以由 Web Receiver 應用程式插入
攔截 LOAD
要求。LoadRequestData
傳回到
Web Receiver SDK 進行處理,並建立播放器。查看更多:
載入媒體時。範例
下方顯示了在 LOAD
請求中新增的手動用戶端拼接廣告
攔截器。
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.mp4';
clipClient.contentType = 'video/mp4';
// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
'break_postroll_client', ['bc_client'], -1);
// Set the ad information in the load request data.
let media = loadRequestData.media;
media.breakClips = [clipClient];
media.breaks = [breakPostrollClient];
return loadRequestData;
});
動態廣告插播
動態廣告插播的特色是在內容播放期間設定廣告插播時間點
播放。方法是取得 BreakManager
的例項並呼叫
這個
addBreak
也能使用 Google Cloud CLI 或
Compute Engine API這至少會使用兩個參數
已展開的內嵌元素
Break
和
陣列
BreakClip
。
選擇性加入的第三個屬性,可強制將變更傳送至
如果在設為 true
時透過 MediaStatus
廣播,已連線至網路的寄件者。時間
新增中斷點及切斷片段,相應的 ID 也不得重複。這些廣告
建立完成後只能新增玩家。Web Receiver SDK 觸發
這個
PLAYER_LOADING
敬上
事件。請參閱以下範例,瞭解
會回應串流 ID3 中繼資料變更的事件處理常式,以及
建立 Break
和 BreakClip
物件,並將其插入時間軸。
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {
// Create the BreakClip.
let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);
// Add the break and break clip.
breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});
移除動態廣告
如要移除動態廣告插播時間點,應用程式應呼叫
removeBreakById
敬上
播放期間的狀況。這個函式會使用中斷點的字串識別碼
就會從時間軸中移除指定的 breakId
必須指向嵌入式
已展開廣告插播。如果偵測到任何其他類型的廣告插播,就會關閉廣告插播
都會保留在時間軸中請參閱下方範例,瞭解如何移除休息時間。
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
breakManager.removeBreakById('break_midroll_embedded_expanded');
廣告插播的行為
SDK 定義了玩家進入和離開休息時間的預設行為
並提供可使用部分 API 進一步自訂的方法
英吋
BreakManager
。
預設中斷行為
透過一般播放或搜尋 Break
進入 Break
時,
SDK 會檢查使用者是否已看過廣告
這個
isWatched
資源。建立時,這個屬性的廣告插播預設值是 false
。如果
屬性為 true
,系統不會在輸入時播放中斷點和主要屬性
內容仍會繼續播放。如果屬性是 false
,就代表
。
搜尋過去的廣告插播時間點時,預設實作會取得所有 Break
position
介於尋求作業的
seekFrom
敬上
和
seekTo
輕鬆分配獎金在這個廣告插播清單中,SDK 會播放 position
的 Break
最接近 seekTo
值,且其 isWatched
屬性已設為
false
。該廣告插播的 isWatched
屬性會設為 true
,而
則播放器就會開始播放廣告插播片段廣告播完後
主要內容會從 seekTo
位置繼續播放。如果沒有
則不會播放中斷,而將繼續播放主要內容
會在 seekTo
位置播放。
在中斷播放期間,SDK 會將所有相關更新播送到
傳送
MediaStatus
。
這些應用程式會讀取廣播訊息,藉由讀取
這個
breakStatus
敬上
資源。這個屬性只會在中斷播放時定義。
接收方應用程式也可以直接查詢與
播放頭的相對於 BreakClip
目前時間的位置
呼叫 PlayerManager
時顯示
getBreakClipCurrentTimeSec
。
同樣地,應用程式可以透過多種方式,查詢目前 BreakClip
的持續時間
撥號中
getBreakClipDurationSec
。
自訂廣告插播行為
預設行為
並使用
setBreakClipLoadInterceptor
敬上
和
setBreakSeekInterceptor
BreakManager
中提供的方法。
休息跳轉攔截器
中斷跳轉攔截器可讓應用程式控制跳轉行為
設定合適的播放時間點要求搜尋作業時,會觸發這個函式
向前或向後跳轉的影片。呼叫這個事件時,
BreakSeekData
敬上
會以參數的形式傳遞至回呼函式。BreakSeekData
物件
包含一個「
Break
position
屬性設為目前
播放頭時間的定義為
seekFrom
以及目的地時間點
seekTo
。
這個攔截器可讓各片段中的 Break
物件
已修改。執行時,中斷跳轉攔截器必須指定哪則廣告
中斷點,藉此傳回選擇性修改的 BreakSeekData
物件。
玩家將繼續播放回傳值中包含的所有廣告插播。如果值
null
的值,或不從中斷搜尋攔截器傳回,斷斷續續就會是
跳過。
請參閱以下範例,瞭解使用攔截器的簡易實作方式 會覆寫預設行為,以觀看透過 已觀看的廣告插播時間點除外
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
breakManager.setBreakSeekInterceptor((breakSeekData) => {
// Filter the breaks array by removing watched breaks.
const unwatchedBreaks =
breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
breakSeekData.breaks = unwatchedBreaks;
return breakSeekData;
});
廣告插播片段載入攔截器
使用中斷片段載入攔截器,即可修改 BreakClip
物件
已開始播放。
系統只會針對
拼接時間表
可使用
setBreakClipLoadInterceptor
。
進入 Break
前,系統會針對每個個人呼叫此攔截器一次
在該廣告插播時間點中定義的 BreakClip
。SDK 會將
BreakClip
敬上
做為回呼函式的參數。接著,應用程式
此 BreakClip
並傳回,讓 SDK 可以擷取並顯示中斷情形
已套用更新設定的剪輯片段。如果未傳回 null
或未傳回任何結果,就代表廣告插播時間點
片段會跳過
以下範例將使用以下參數修改廣告插播片段的 contentUrl
:
公用程式函式呼叫 getUrlFromClipId
,其中 BreakClip
的 id
對應至一個網址
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
breakManager.setBreakClipLoadInterceptor(
(breakClip, breakClipLoadInterceptorContext) => {
// Obtains the URL of a break clip id from a function call.
breakClip.contentUrl = getUrlFromClipId(breakClip.id);
return breakClip;
});
略過廣告
Web Receiver SDK 提供的 API 可以略過廣告插播和個別廣告插播片段 顯示與內容相同的結果SDK 也可讓使用者選擇按照 與傳送者應用程式或智慧螢幕裝置互動。
使用者可略過的廣告插播短片
將廣告插播片段設為可略過,使用者就能與已連線的傳送者互動
應用程式和智慧螢幕,您也可以選擇
。將
whenSkippable
敬上
設為非負數的秒數,就能為
BreakClip
物件。播放完畢之後
中斷片段已播放達該秒數將這個值設為 0
可讓使用者立即略過廣告插播片段。
// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.
這項資訊可在傳送者的原始載入要求中設定,或在 接收器應用程式。略過時,系統會在已合併的時間軸廣告插播時間點顯示廣告插播片段 會停止播放目前的休息片段播放器就會載入 中斷片段 (如果有的話) 或載入主要內容。略過時,系統會在 內嵌時間軸的廣告插播會跳轉到廣告插播片段的結尾, 繼續播放串流。
透過程式輔助方式略過廣告
也可以在沒有使用者互動的情況下自動略過廣告。
如要跳過「整個休息時間」,應用程式應將
isWatched
敬上
Break
到 true
的屬性。在載入期間隨時可以完成這項作業
例如序列或內容播放isWatched
屬性會由
當主要內容的目前時間符合中斷點的 position
時,就會玩家。在
播放到這點後,播放器會決定是否應輸入休息時間。
請查看下列範例,系統會循環顯示所有的廣告插播情形,並修改
值。
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
(event) => {
// Obtain the breaks and iterate through each item to skip all ad breaks.
let breaks = breakManager.getBreaks();
breaks.forEach((brk) => {
brk.isWatched = true;
});
});
如要透過程式輔助方式略過特定廣告插播片段,
應使用中斷片段載入攔截器。變更者:
在回呼函式中傳回 null
或不傳回值,
系統就會略過這個廣告插播時間點
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();
breakManager.setBreakClipLoadInterceptor(
(breakClip, breakClipLoadInterceptorContext) => {
return null;
});