廣告規則

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

立即體驗

您可以在下方查看實際執行的方式。

跳轉功能的相關問題

如果您使用廣告規則,可能會遇到點擊並拖曳跳轉問題。 具體來說,當使用者點按並拖曳多個片中廣告 Pod 時,可能會先播放 2 個以上的 Pod 回歸,再繼續播放內容。這是因為影片播放頭時間在使用者尋找的同時更新;如果 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 屬性。