IMA HTML5 SDK 支援全自動廣告播放清單。這項功能會在投放廣告時,將廣告插播時間點插入 Google Ad Manager 中指定的內容。此外,它也大幅簡化了支援廣告插播所需的影片播放器程式碼,包括片頭廣告、片中廣告和片尾廣告。
- 建立
AdsManager
時,系統會透過 getAdsManager 呼叫傳入contentPlayback
物件。這個物件必須具備會傳回影片目前播放頭位置的currentTime
屬性。如果您使用 HTML5video
元素顯示內容,只要將該元素傳遞至 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(); }
立即體驗
您可以在下方查看實際執行的方式。
跳轉功能的相關問題
如果您使用廣告規則,可能會遇到點擊並拖曳跳轉問題。 具體來說,當使用者點按並拖曳多個片中廣告 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
屬性。