自動化廣告播放清單

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_REQUESTEDCONTENT_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 屬性。