自動化廣告播放清單

IMA HTML5 SDK 支援全自動廣告播放清單。這項功能會在您放送廣告時，將 Google Ad Manager 中指定的廣告插播插入內容中。這也大幅簡化了支援廣告插播所需的影片播放器程式碼，包括片頭、片中和片尾廣告。

  • 建立 AdsManager 時，系統會使用 getAdsManager 呼叫傳入 contentPlayback 物件。這個物件必須具有 currentTime 屬性，可傳回影片目前的播放頭位置。如果您使用 HTML5 video 元素顯示內容，可以直接將該元素傳遞至 SDK。這個物件可用於追蹤內容播放進度，以便在 Ad Manager 指定的時間自動插入廣告插播。您也必須讓 SDK 知道您希望由 SDK 代為處理內容狀態。
    var adsRenderingSettings = new google.ima.AdsRenderingSettings();
adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
adsManager = adsManagerLoadedEvent.getAdsManager(
    videoContent, adsRenderingSettings); // See API reference for contentPlayback.
  • 為確保片尾廣告播放，您必須讓 SDK 知道內容播放完畢的時間。這有點棘手，因為在某些情況下，SDK 會使用您的影片播放器播放廣告，因此您必須確保只讓 SDK 知道內容播放完畢的時間，而非廣告播放完畢的時間。您可以使用下列程式碼執行這項操作：
    var videoContent = document.getElementById('contentElement');
var contentEndedListener = function() {adsLoader.contentComplete();};

videoContent.addEventListener('ended', contentEndedListener);

function onContentPauseRequested() {
  contentElement.removeEventListener('ended', contentEndedListener);
  ...
}

function onContentResumeRequested() {
  contentElement.addEventListener('ended', contentEndedListener);
  ...
}
  • 播放廣告插播時，系統會使用 CONTENT_PAUSE_REQUESTED 和 CONTENT_RESUME_REQUESTED 事件暫停及繼續播放內容。
  • 如果影片播放器支援拖曳尋找功能，且影片播放器的目前時間屬性在使用者拖曳時更新，SDK 就無法區分內容是否正在正常播放，以及使用者是否正在尋找內容。您必須使用自訂 contentPlayback 物件做為 getAdsManager 的參數。如需此用法的範例，請參閱「尋找問題」。

注意：當內容播放完畢或使用者停止播放時，請務必呼叫 AdsLoader.contentComplete，以便向 SDK 發出內容已完成的信號。接著，如果已排定片尾廣告插播時間，SDK 就會播放片尾廣告插播。播放完所有廣告插播後，系統會觸發 ALL_ADS_COMPLETED 事件。此外，請注意，內容追蹤會在呼叫 init() 時開始，因此請務必在播放內容前呼叫 init()。

停用自動播放廣告插播功能

在某些情況下，您可能會希望 SDK 在您準備好播放廣告插播前，不要播放廣告插播。在這種情況下，您可以停用自動播放廣告插播功能，並讓 SDK 知道何時播放廣告插播。在這個設定中，SDK 載入廣告插播後，就會觸發 AD_BREAK_READY 事件。當播放器準備好開始廣告插播時，您可以呼叫 adsManager.start():

function requestAds() {}
  ...
  adsLoader.getSettings().setAutoPlayAdBreaks(false);
  ...
}

function onAdsManagerLoaded() {
  ...
  // For non-auto ad breaks, listen for ad break ready
  adsManager.addEventListener(
      google.ima.AdEvent.Type.AD_BREAK_READY,
      adBreakReadyHandler);
  ...
}

function adBreakReadyHandler() {
  // Once we're ready to play ads. To skip this ad break, simply return
  // from this handler without calling adsManager.start().
  adsManager.start();
}

立即試用

請參閱下列程式碼，瞭解如何實作。

尋找問題

如果你使用廣告規則，可能會遇到點選拖曳尋找的問題。具體來說，當使用者點選並拖曳以在影片中跳過多個中插廣告時，可能會看到 2 個以上的中插廣告連續播放，然後才會繼續播放內容。這是因為影片播放頭時間會在使用者暫停時更新；如果 SDK 在使用者暫停廣告後，恰好輪詢目前時間，可能會認為應播放廣告。內容繼續播放時，系統會播放該廣告，然後播放從快轉點開始播放的最新廣告。如需這項問題的視覺化呈現方式，請參閱下列圖表：

請在使用者開始尋找時儲存目前的時間，並在 SDK 要求時回報該時間，直到使用者恢復正常播放為止。如需這項解決方案的視覺化呈現方式，請參閱下圖：

透過這項解決方案，您可以正確略過 0:10 中插廣告，並只播放 0:20 中插廣告。如要完成這項操作，請在下列程式碼片段中使用自訂播放頭追蹤器。這個程式碼包含進階 HTML5 範例中的 ads.js 修改內容 (以粗體顯示)，該範例可在下載頁面中找到。

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.videoPlayer_.contentPlayer.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

Safari 行動版的已知問題

這個方法應該適用於所有平台，除了行動版 Safari 以外。在行動版 Safari 上，影片標記的尋找屬性未正確導入 (一律傳回 false)。為避免這種情況，您必須自行檢查，確認使用者是否正在尋找影片。以下是這個方法的程式碼範例。再次提醒，加粗的程式碼行是對現有程式碼的修改。

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
  this.seeking = false;
  this.seekCheckInterval = 1000;
  // You may need to adjust this value, depending on your platform
  this.seekThreshold = 100;
  this.previousTime = 0;
  setInterval(
      Application.bind(this, this.checkForSeeking),
      this.seekCheckInterval);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.checkForSeeking = function() {
  var currentTime = this.videoPlayer_.contentPlayer.currentTime;
  // How much time has passed since you last ran this method, in milliseconds
  var diff = (currentTime - this.previousTime) * 1000;
  // If that difference is greater than the time since you last ran this method,
  // plus the threshold, the user was seeking
  if (Math.abs(diff)  > this.interval + this.threshold) {
    this.seeking = true;
  } else {
    this.seeking = false;
  }
  // Grab the current video time again to make up for time spent in this method
  previousTime = this.videoPlayer_.contentPlayer.currentTime;
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

在進行這些變更後，SDK 會使用 Ads 物件的 currentTime 屬性，判斷何時播放廣告插播，而非內容影片播放器的 currentTime 屬性。