廣告插播時間點

總覽

Web Receiver SDK 原生支援廣告插播和隨播廣告 特定媒體串流中的各個事件它提供的 API 可設定廣告排序、廣告來源 以及廣告插播的行為和相關聯的廣告插播片段在本指南中， Break敬上 是指包含一或多則廣告/串場廣告的播放間隔， 每則廣告或串場廣告稱為 BreakClip。 這些廣告插播時間點與載入中或播放的媒體相關聯。

廣告類型

Web Receiver SDK 支援用戶端廣告插播 (CSAI) 和伺服器 拼接式廣告插播 (SSAI)。客戶拼接廣告可以是由 或從 VAST 和 VMAP 範本檔案擷取的應用程式。 「伺服器拼接」廣告必須在載入內容之前手動指定， 內嵌廣告，或在內容播放期間以動態方式播放內嵌式已展開的廣告 廣告。下文將詳細說明每一種廣告類型的導入作業。

// 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.

// 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.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"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"
  }
]

// 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;

// 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.

// 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 時間軸上。選取時間軸後，就不能變更目前設定的時間軸 媒體項目。下表提供每個時間軸的詳細說明。

下方圖 1 至 3 說明部分內容包含各種廣告類型及 以及個別時間軸值內容設有片頭廣告插播時間點 包含兩個廣告插播片段，以及片中和片尾這兩種廣告插播時間點 一個廣告插播片段從內容開始播放以來的實際時間。 主要內容的媒體時間，以及廣告插播目前的時間 播放中斷影片時，會在每個圖形下方對齊。

分隔位置設定

Web Receiver SDK 可讓開發人員指定廣告插播時間點 放置在 position敬上 Break 屬性。這個值會對應至主要內容的媒體時間 以及建立 pre-roll、mid-roll 和 post-roll 廣告插播時間點。 定義如下：

互通性矩陣

為方便您快速參考，表 1 列出了各種廣告類型 以及廣告相關功能的相容性

活動

當發生按鍵中斷事件時，cast SDK 會分派類型的事件 BreaksEvent。 接收器應用程式可以使用 PlayerManager 訂閱 addEventListener 也能使用 Google Cloud CLI 或 Compute Engine API

這些事件可用於分析和廣告播放。採用 VMAP 時 (影片多重廣告播放清單) 和 VAST (影片廣告放送範本) 廣告 ，回應中提供的任何標準追蹤事件都會自動 自動調度 Pod 資源

事件類型列於表 2 及相關詳細說明 觸發時。

插入廣告

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;
});