1. 總覽
本程式碼研究室將說明如何建構使用 Cast Ad Breaks API 的自訂 Web Receiver 應用程式。
什麼是 Google Cast？
Google Cast 可讓使用者將行動裝置上的內容投放到電視上。讓使用者能將行動裝置當做電視播放媒體的遙控器。
Google Cast SDK 可讓您擴充應用程式，輕鬆控制電視或音響系統。Cast SDK 可讓您根據 Google Cast 設計檢查清單新增必要的 UI 元件。
「Google Cast 設計檢查清單」旨在將 Cast 實作方式標準化，讓使用者可在所有支援的平台上享有直覺的體驗。
我們要建構什麼？
完成本程式碼研究室後，您就建構了能利用 Break API 的 Cast 接收器。
課程內容
- 如何在投放內容中加入 VMAP 和 VAST 廣告插播
- 如何略過廣告插播片段
- 如何自訂跳轉時的預設中斷行為
軟硬體需求
- 最新版的 Google Chrome 瀏覽器。
- HTTPS 代管服務，例如 Firebase 託管或 ngrok。
- 一部 Google Cast 裝置，例如已設定網際網路連線的 Chromecast 或 Android TV。
- 具備 HDMI 輸入端的電視或螢幕，或是 Google Home Hub
功能
請確保您具備下列經驗，再繼續完成本程式碼研究室。
- 具備一般網頁開發知識。
- 建構投放網路接收器應用程式。
您將會如何使用這個教學課程？
針對建構網頁應用程式的體驗，您會給予什麼評價？
2. 取得程式碼範例
將所有程式碼範例下載至電腦...
然後將下載的 ZIP 檔案解壓縮
3. 在本機部署接收器
如要搭配投放裝置使用網路接收器，您必須將裝置代管於支援 Cast 裝置的位置。如果您已擁有支援 https 的伺服器，請略過下列步驟，並記下網址 (下一節會用到)。
如果沒有可以使用的伺服器，可以使用 Firebase 託管或 ngrok。
執行伺服器
設定完畢後，請前往 app-start 並啟動伺服器。
記下代管接收器的網址。您會在下一節中用到。
4. 在 Cast 開發人員控制台註冊應用程式
您必須註冊應用程式，才能在 Chromecast 裝置上執行自訂接收器，就像本程式碼研究室的內建功能。註冊應用程式後，系統會產生應用程式 ID，因為寄件者應用程式必須設定成啟動 Web Receiver 應用程式。
按一下「新增應用程式」
選取「自訂接收端」，這就是我們正在建構的項目。
輸入新接收者的詳細資料。請務必使用指向您計劃代管 Web Receiver 應用程式的網址。請記下您註冊應用程式後由控制台產生的應用程式 ID。傳送者應用程式將在後續章節中設定為使用該 ID。
此外，您也必須註冊 Google Cast 裝置，這樣裝置才能在您發布前存取接收器應用程式。發布接收器應用程式後，即可供所有 Google Cast 裝置使用。就本程式碼研究室而言，建議您使用未發布的接收器應用程式。
按一下「新增裝置」
輸入印在 Google Cast 裝置背面的序號，然後設定一個描述性名稱。存取 Google Cast SDK 開發人員控制台時，在 Chrome 中投放畫面，也可以找到序號
接收端和裝置可能需要 5 到 15 分鐘才能進行測試。等待 5 到 15 分鐘後，您必須重新啟動投放裝置。
5. 準備 Start 專案
開始執行本程式碼研究室前，建議您先參閱 Google Ads 開發人員指南，概略瞭解廣告插播 API。
必須先將 Google Cast 支援功能新增至您下載的啟動應用程式。以下是本程式碼研究室使用的一些 Google Cast 術語：
- 傳送者應用程式是在行動裝置或筆記型電腦上執行，
- 接收端應用程式必須在 Google Cast 裝置上執行。
您現在可以使用喜愛的文字編輯器，以範例專案為基礎進行建構了：
- 從程式碼範例下載中選取
app-start目錄。 - 開啟
js/receiver.js和 index.html
請注意，當您在本程式碼研究室中操作時，您選擇的網站代管解決方案應該會隨之更新。繼續驗證及測試變更時，請務必將變更推送至代管網站。
應用程式設計
如先前所述，程式碼研究室會使用傳送端應用程式啟動投放工作階段，以及用於修改為使用廣告插播 API 的接收器應用程式。
在本程式碼研究室中，投放和指令工具將做為網路傳送者來啟動接收器應用程式。首先，請在 Chrome 瀏覽器中開啟這項工具。輸入您在 Cast SDK 開發人員控制台中提供的接收端應用程式 ID，然後按一下「設定」，設定用於測試的傳送者應用程式。
注意：如果系統未顯示投放圖示，請確認已在 Cast 開發人員控制台正確註冊網路接收器和投放裝置。將剛剛註冊的任何投放裝置重新開機 (如果尚未重新啟動)。
接收器應用程式是本程式碼研究室的主要重點，包含 index.html 中定義的一個主要檢視畫面和一個名為 js/receiver.js 的 JavaScript 檔案。下文將進一步說明這些內容。
index.html
這個 HTML 檔案包含 cast-media-player 元素所提供接收器應用程式的 UI。還會載入 CAF SDK 和 Cast Debug Logger 程式庫。
receiver.js
此指令碼會管理接收器應用程式的所有邏輯。現在包含基本的 CAF 接收器，用於初始化投放結構定義，並在初始化時載入影片資產。我們還新增了一些偵錯記錄工具功能，將記錄傳回至 Cast 和 Command 工具。
6. 在內容中加入 VMAP
Cast Web Receiver SDK 支援透過數位影片多重廣告播放清單 (也稱為 VMAP) 指定的廣告。XML 結構會指定媒體的廣告插播時間點，以及相關的廣告插播片段中繼資料。如要插入這些廣告，SDK 會在 MediaInformation 物件中提供 vmapAdsRequest 屬性。
在 js/receiver.js 檔案中，建立 VastAdsRequest 物件。找出「LOAD 要求攔截器」函式，並將其替換為以下程式碼。這個檔案包含 DoubleClick 提供的 VMAP 廣告代碼網址範例，並提供隨機的 correlator 值，可確保對同一個網址發出的後續請求可產生 XML 範本，其中包含尚未觀看過的廣告插播時間點。
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
const vmapUrl =
'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
Math.floor(Math.random() * Math.pow(10, 10));
let vmapRequest = new cast.framework.messages.VastAdsRequest();
vmapRequest.adTagUrl = vmapUrl;
loadRequestData.media.vmapAdsRequest = vmapRequest;
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
將變更儲存至 js/receiver.js，然後將檔案上傳至網路伺服器。按一下 投放圖示，在「投放與指令工具」上啟動投放工作階段。VMAP 廣告應會先播放，接著是主要內容。
7. 在您的內容中加入 VAST
如前所述，Web Receiver SDK 支援多種廣告類型。本節重點介紹可用來整合數位影片廣告放送範本廣告 (也稱為 VAST) 的 API。如果您已導入上一節的 VMAP 程式碼，請加註。
在載入要求攔截器後，將下列內容複製到 js/receiver.js 檔案中。其中包含來自 DoubleClick 的六個 VAST 廣告插播片段和隨機的 correlator 值。系統會將這些廣告插播片段指派到 5 個廣告插播時間點。每個廣告插播的 position 都設為與主要內容相關的時間 (以秒為單位)，包括片頭廣告 (position 設為 0) 和片尾廣告 (將 position 設為 -1) 的廣告插播時間點。
const addVASTBreaksToMedia = (mediaInformation) => {
mediaInformation.breakClips = [
{
id: 'bc1',
title: 'bc1 (Pre-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('preroll')
}
},
{
id: 'bc2',
title: 'bc2 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc3',
title: 'bc3 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc4',
title: 'bc4 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc5',
title: 'bc5 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc6',
title: 'bc6 (Post-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('postroll')
}
}
];
mediaInformation.breaks = [
{id: 'b1', breakClipIds: ['bc1'], position: 0},
{id: 'b2', breakClipIds: ['bc2'], position: 15},
{id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
{id: 'b4', breakClipIds: ['bc5'], position: 100},
{id: 'b5', breakClipIds: ['bc6'], position: -1}
];
};
注意：中斷點的 breakClipIds 屬性是陣列，這表示可以為各個廣告插播指派多個片段片段。
在 js/receiver.js file 中找出 LOAD 訊息攔截器，並替換成以下程式碼。請注意，VMAP 工作會加上註解，以顯示 VAST 類型廣告。
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
// const vmapUrl =
// 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
// Math.floor(Math.random() * Math.pow(10, 10));
// let vmapRequest = new cast.framework.messages.VastAdsRequest();
// vmapRequest.adTagUrl = vmapUrl;
// loadRequestData.media.vmapAdsRequest = vmapRequest;
// Append VAST ad breaks to the MediaInformation.
addVASTBreaksToMedia(loadRequestData.media);
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
將變更儲存至 js/receiver.js，然後將檔案上傳至網路伺服器。按一下 投放圖示，在「投放與指令工具」上啟動投放工作階段。VAST 廣告會先播放，接著是主要內容。
8. 廣告插播略過
CAF 具有一個名為 BreakManager 的類別，可協助您針對廣告行為導入自訂業務規則。其中一項功能可讓應用程式根據特定條件，以程式輔助方式略過廣告插播及中斷短片片段。這個範例說明如何略過位置在內容前 30 秒 (但不含片尾) 的廣告插播。使用上一節設定的 VAST 廣告時，定義了 5 個廣告插播時間點：1 個片頭廣告插播、3 個片中廣告 (15、60 秒和 100 秒)，最後是一個片尾廣告插播。完成這些步驟後，系統只會略過位置為 15 秒的片頭廣告和片中廣告。
為此，應用程式應透過 BreakManager 呼叫可用的 API，藉此設定中斷載入的攔截器。將下列程式碼複製到 js/receiver.js 檔案中，位於包含 context 和 playerManager 變數的行之後，以便取得執行個體的參照。
const breakManager = playerManager.getBreakManager();
應用程式應使用規則設定攔截器，忽略任何片尾廣告插播 30 秒前發生的廣告插播，同時記住所有片尾廣告插播時間點 (因為 position 值為 -1)。這個攔截器的運作方式與 PlayerManager 的 LOAD 攔截器類似，差別在於這個攔截器專門用於載入廣告插播片段。在 LOAD 要求攔截器之後，以及 addVASTBreaksToMedia 函式宣告之前設定此屬性。
將下列內容複製到 js/receiver.js 檔案中。
breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
/**
* The code will skip playback of break clips if the break position is within
* the first 30 seconds.
*/
let breakObj = breakContext.break;
if (breakObj.position >= 0 && breakObj.position < 30) {
castDebugLogger.debug(
'MyAPP.LOG',
'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
return null;
} else {
return breakClip;
}
});
注意：在此傳回 null 會略過正在處理的 BreakClip。如果 Break 未定義任何廣告插播片段，系統會略過廣告插播本身。
將變更儲存至 js/receiver.js，然後將檔案上傳至網路伺服器。按一下 投放圖示，在「投放與指令工具」上啟動投放工作階段。應處理 VAST 廣告。請注意，系統不會播放片頭廣告和第一個片中廣告 (position 為 15 秒) 的廣告。
9. 自訂休息搜尋行為
尋找過去的插播時，預設實作會取得位置介於搜尋作業 seekFrom 與 seekTo 值之間的所有 Break 項目。在此中斷清單中，SDK 會播放 Break，其 position 最接近 seekTo 值，且 isWatched 屬性已設為 false。該廣告插播的 isWatched 屬性隨後會設為 true，播放器就會開始播放插播影片。觀看中斷後，主要內容會從 seekTo 位置繼續播放。如果沒有這類中斷點，系統就不會播放任何中斷點，而主要內容會在 seekTo 位置繼續播放。
如要自訂跳轉時播放的中斷時間點，Cast SDK 在 BreakManager 中提供 setBreakSeekInterceptor API。當應用程式透過該 API 提供其自訂邏輯時，每當執行搜尋作業的一或多個中斷時，SDK 都會呼叫 API。系統會傳遞回呼函式的物件，當中包含 seekFrom 位置與 seekTo 位置之間的所有中斷點。接著，應用程式需要修改並傳回 BreakSeekData。
以下範例會覆寫預設行為，擷取所有跳轉的廣告插播，並且只播放時間軸中出現的第一個廣告插播。
請將下列內容複製到 js/receiver.js 檔案中的 setBreakClipLoadInterceptor 檔案內。
breakManager.setBreakSeekInterceptor((breakSeekData) => {
/**
* The code will play an unwatched break between the seekFrom and seekTo
* position. Note: If the position of a break is less than 30 then it will be
* skipped due to the setBreakClipLoadInterceptor code.
*/
castDebugLogger.debug(
'MyAPP.LOG',
'Break Seek Interceptor processing break ids ' +
JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));
// Remove all other breaks except for the first one.
breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
return breakSeekData;
});
注意：如果函式未傳回值或傳回 null，就不會播放任何中斷點。
將變更儲存至 js/receiver.js，然後將檔案上傳至網路伺服器。按一下 投放圖示，在「投放與指令工具」上啟動投放工作階段。應處理 VAST 廣告。請注意，系統不會播放片頭廣告和第一個片中廣告 (position 為 15 秒) 的廣告。
等待播放時間達到 30 秒，看完片段載入攔截器略過的所有廣告插播時間點。提出要求後，可前往「媒體控制」分頁分派搜尋指令。在「Seek Into Media」輸入填入 300 秒，然後按一下「TO」按鈕。記下「Break Seek Interceptor」中顯示的記錄。預設行為現在應覆寫，以便在更接近 seekFrom 時間的情況下播放廣告插播。
10. 恭喜
您已瞭解如何使用最新的 Cast Receiver SDK，在接收器應用程式中加入廣告。
詳情請參閱廣告插播開發人員指南。