在影片內容中顯示廣告

發行項
03/28/2024

警告

自 2020 年 6 月 1 日起，Windows UWP 應用程式的 Microsoft 廣告收益平台將會關閉。深入了解

本逐步解說示範如何使用AdScheduler 類別，在使用 JavaScript 搭配 HTML 撰寫的通用 Windows 平台 (UWP) 應用程式中顯示影片內容中的廣告。

注意

此功能目前僅支援使用 JavaScript 搭配 HTML 撰寫的 UWP 應用程式。

AdScheduler 可搭配漸進式和串流媒體使用，並使用 IAB 標準視訊廣告服務範本 (VAST) 2.0/3.0 和 VMAP 承載格式。透過遵循標準，AdScheduler 與它互動的廣告服務無關。

視訊內容的廣告會根據程式是否低於十分鐘 (短片格式)，或超過十分鐘 (長片格式) 而有所不同。雖然後者在服務上設定更為複雜，但實際上在撰寫用戶端程式碼的方式上並沒有差異。如果 AdScheduler 收到單一廣告的 VAST 承載而非資訊清單，則將其視為資訊清單要求單一前導廣告 (於 00:00 時間播放)。

必要條件

使用 Visual Studio 2015 或更新版本安裝 Microsoft Advertising SDK。
您的專案必須使用 MediaPlayer 控制項來提供廣告排程所在的視訊內容。此控制項可在 GitHub 上從 Microsoft 取得的程式庫的 TVHelpers 集合中取得。

下列範例示範如何在 HTML 標記中宣告 MediaPlayer。一般而言，此標記屬於 index.html 檔案 (或適合您專案的另一個 html 檔案) 中的 <body> 區段。
```
<div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
  <video src="URL to your content">
  </video>
</div>
```
下列範例示範如何在 JavaScript 程式碼中建立 MediaPlayer。
```
var mediaPlayerDiv = document.createElement("div");
document.body.appendChild(mediaPlayerDiv);

var videoElement = document.createElement("video");
videoElement.src = "<URL to your content>";
mediaPlayerDiv.appendChild(videoElement);

var mediaPlayer = new TVJS.MediaPlayer(mediaPlayerDiv);
```

如何在程式碼中使用 AdScheduler 類別

在 Visual Studio 中，打開專案或建立新專案。
如果您的專案以 [任何 CPU] 為目標，請更新您的專案以使用架構特定的組建輸出 (例如 x86)。如果您的專案以 [任何 CPU] 為目標，您將無法在下列步驟中成功新增 Microsoft Advertising 程式庫的參考。如需詳細資訊，請參閱在專案中以任何 CPU 為目標所造成的參考錯誤。
將 Microsoft Advertising SDK for JavaScript 程式庫的參考新增至您的專案。
1. 從 [方案總管] 視窗，以滑鼠右鍵按一下 [參考]，然後選取 [新增參考...]。
2. 在 [參考管理員] 中，展開 [通用 Windows]，按一下 [延伸模組]，然後選取 [Microsoft Advertising SDK for JavaScript] (10.0 版) 旁的核取方塊。
3. 在 [參考管理員] 中，按一下 [確定]。
將 AdScheduler.js 檔案新增至您的專案：
1. 在 Visual Studio 中，按一下 [專案] 和 [管理 NuGet 套件]。
2. 在搜尋方塊中，輸入 Microsoft.StoreServices.VideoAdScheduler，並安裝 Microsoft.StoreServices.VideoAdScheduler 套件。 AdScheduler.js 檔案會新增至專案中的 ../js 子目錄。
開啟 index.html 檔案(或其他適用於您專案的 HTML 檔案)。在 <head> 區段中，在專案的 javaScript 參考 default.css 和 main.js 之後，會將參考新增至 ad.js 和 adscheduler.js。
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
<script src="/js/adscheduler.js"></script>
```
注意

在包含 main.js 之後，這一行必須放在 <head> 區段中；否則，當您建置專案時會發生錯誤。
在專案中 main.js 檔案中，新增程式碼以建立新的 AdScheduler 物件。傳入裝載視訊內容的 MediaPlayer。程序碼必須放置在適當位置，使其在 WinJS.UI.processAll 之後執行。
```
var myMediaPlayer = document.getElementById("MediaPlayerDiv");
var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
```
使用 AdScheduler 物件的 requestSchedule 或 requestScheduleByUrl 方法，從伺服器要求廣告排程，並將其插入 MediaPlayer 時間軸，然後播放視訊媒體。
- 若您是 Microsoft 的合作夥伴，並已獲准向 Microsoft 廣告伺服器請求廣告排程，請使用 requestSchedule ，並指定您的應用程式識別碼和廣告單元識別碼，這些資訊是由 Microsoft 代表提供。
  
  這個方法以 Promise 的形式呈現，這是一種非同步構造，其中傳遞了兩個函式指標：一個是當 Promise 成功完成時呼叫的 onComplete 函式指標，另一個是遇到錯誤時呼叫的 onError 函式指標。在 onComplete 函式中，開始播放您的視訊內容。廣告將在排程時間開始播放。在 onError 函式中，處理錯誤，然後開始播放您的視訊。您的影片內容將會在沒有廣告的情況下播放。 onError 函式的引數是包含下列成員的物件。
```
myAdScheduler.requestSchedule("your application ID", "your ad unit ID").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.tvControl.play();
  },
  function promiseErrorHandler(err) {
      // Error: play the video content without the ads.
      myMediaPlayer.tvControl.play();
  });
```
- 若要從非 Microsoft 廣告伺服器要求廣告排程，請使用 requestScheduleByUrl，並傳入伺服器 URI。此方法也採用 Promise 的形式，可接受 onComplete 和 onError 函式的指標。從伺服器傳回的廣告承載必須符合視訊廣告服務範本 (VAST) 或視訊多廣告播放清單 (VMAP) 承載格式。
```
myAdScheduler.requestScheduleByUrl("your URL").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.winControl.play();
  },
  function promiseErrorHandler(evt) {
      // Error: play the video content without the ads.
      myMediaPlayer.winControl.play();
  });
```
注意

您應該等候 requestSchedule 或 requestScheduleByUrl 傳回，再開始在 MediaPlayer 中播放主要視訊內容。在 requestSchedule 傳回之前 (在前導廣告的情況下)，開始播放媒體將導致前導中斷主要影片內容。即使函式失敗，您也必須呼叫 play，因為 AdScheduler 會告訴 MediaPlayer 略過廣告並直接移至內容。您可能有不同的商務需求，例如，如果無法從遠端擷取廣告，則插入內建廣告。

在播放期間，您可以處理其他事件，讓您的應用程式追蹤進度和/或錯誤，這些事件可能會在初始廣告比對處理序之後發生。下列程式代碼顯示其中一些事件，包括 onPodStart、onPodEnd、onPodCountdown、onAdProgress、onAllComplete 和 onErrorOccurred。

// Raised when an ad pod starts. Make the countdown timer visible.
myAdScheduler.onPodStart = function (sender, data) {
    myCounterDiv.style.visibility = "visible";
}

// Raised when an ad pod ends. Hide the countdown timer.
myAdScheduler.onPodEnd = function (sender, data) {
    myCounterDiv.style.visibility = "hidden";
}

// Raised when an ad is playing and indicates how many seconds remain  
// in the current pod of ads. This is useful when the app wants to show 
// a visual countdown until the video content resumes.
myAdScheduler.onPodCountdown = function (sender, data) {
    myCounterText = "Content resumes in: " +
    Math.ceil(data.remainingPodTime) + " seconds.";
}

// Raised during each quartile of progress through the ad clip.
myAdScheduler.onAdProgress = function (sender, data) {
}

// Raised when the ads and content are complete.
myAdScheduler.onAllComplete = function (sender) {
}

// Raised when an error occurs during playback after successfully scheduling.
myAdScheduler.onErrorOccurred = function (sender, data) {
}

AdScheduler 成員

本節提供 AdScheduler 物件成員的一些詳細資料。如需這些成員的詳細資訊，請參閱您專案中 AdScheduler.js 檔案中的註解和定義。

requestSchedule

這個方法會向 Microsoft 廣告伺服器要求廣告排程，並將它插入傳遞至 AdScheduler 建構函式的 MediaPlayer 時間軸中。

選擇性的第三個參數 (adTags) 是名稱/值組的 JSON 集合，可用於具有進階目標的應用程式。例如，播放各種汽車相關影片的應用程式，可能會以顯示汽車的製造商和型號來補充廣告單元識別碼。此參數僅供從 Microsoft 獲得核准的合作夥伴使用，以使用廣告標籤。

參考 adTag 時，應該注意下列項目：

此參數是很少使用的選項。發行者必須先與 Microsoft 密切合作，才能使用 adTags。
名稱和值都必須在廣告服務上預先決定。廣告標籤不是開放式搜尋字詞或關鍵詞。
支援的標籤上限為 10 個。
標籤名稱限制為 16 個字元。
標籤值最多可有 128 個字元。

requestScheduleByUri

這個方法會從 URI 中指定的非 Microsoft 廣告伺服器要求廣告排程，並將它插入傳遞至 AdScheduler 建構函式的 MediaPlayer 時間軸中。由廣告伺服器傳回的廣告承載必須符合視訊廣告服務範本 (VAST) 或視訊多廣告播放清單 (VMAP) 承載格式。

mediaTimeout

這個屬性會取得或設定媒體必須可播放的毫秒數。值為 0 會通知系統永不逾時。預設值為 30000 毫秒 (30 秒)。

playSkippedMedia

這個屬性會取得或設定 Boolean 值，這個值表示如果使用者提前跳到排程開始時間超過某個點，排程的媒體是否會播放。

廣告客戶端和媒體播放器會根據主要視訊內容的快轉和倒轉期間，對廣告會發生什麼情況強制執行規則。在大部分情況下，應用程式開發人員不允許完全略過廣告，但確實希望為使用者提供合理的體驗。大部分開發人員的需求屬於下列兩個選項：

允許終端使用者暫時略過廣告單元。
允許使用者略過廣告單元，但在播放繼續時播放最新的單元。

playSkippedMedia 屬性有下列條件：

一旦廣告開始，就無法略過或快轉廣告。
一旦廣告單元啟動，廣告單元中的所有廣告都會播放。
一旦播放，廣告將不會在主要內容 (電影、單集等) 期間再次播放：廣告標記會標示為播放或移除。
前導廣告無法略過。

恢復包含廣告的內容時，請將 playSkippedMedia 設定為 false 以略過前導廣告，並防止最近的廣告中斷播放。然後，在內容開始之後，將 playSkippedMedia 設定為 true，以確保使用者無法透過後續的廣告快轉。

注意

廣告單元是一組依序播放的廣告，例如在商業休息期間播放的廣告群組。如需詳細資訊，請參閱 IAB 數位視訊廣告服務範本 (VAST) 規格。

requestTimeout

這個屬性會取得或設定在逾時之前等待廣告要求回應的毫秒數。值為 0 會通知系統永不逾時。預設值為 30000 毫秒 (30 秒)。

排程

這個屬性會取得從廣告伺服器擷取的排程資料。此物件包含與視訊廣告服務範本 (VAST) 或視訊多廣告播放清單 (VMAP) 承載結構對應的完整資料階層。

onAdProgress

當廣告播放達到四分位數檢查點時，就會引發此事件。事件處理常式 (eventInfo) 的第二個參數是具有下列成員的 JSON 物件：

progress：廣告播放狀態 (AdScheduler.js 中定義的其中一個 MediaProgress 列舉值)。
clip：正在播放的視訊剪輯。此物件不適用於您的程序碼。
adPackage：物件，代表對應至正在播放之廣告的廣告承載部分。此物件不適用於您的程序碼。

onAllComplete

當主要內容到達結尾，且任何排程的結尾廣告也結束時，就會引發此事件。

onErrorOccurred

當 AdScheduler 遇到錯誤時，就會引發此事件。如需錯誤碼值的詳細資訊，請參閱 ErrorCode。

onPodCountdown

當廣告正在播放，並指出目前廣告單元剩餘多少時間時，就會引發此事件。事件處理常式 (eventData) 的第二個參數是具有下列成員的 JSON 物件：

remainingAdTime：目前廣告剩餘的秒數。
remainingPodTime：目前廣告單元剩餘的秒數。

注意