您可以使用 IMA SDK 輕鬆將多媒體廣告整合至網站和應用程式。IMA SDK 可向任何 符合 VAST 規定的廣告伺服器要求廣告,並管理應用程式中的廣告播放作業。使用 IMA 用戶端 SDK 時,您可以繼續控制內容影片播放,而 SDK 則負責處理廣告播放。廣告會在位於應用程式內容影片播放器頂端的獨立影片播放器中播放。
本指南將說明如何將 IMA SDK 整合至簡易的影片播放器應用程式。如要查看或參考已完成整合的範例,請從 GitHub 下載簡易範例。如果您有興趣使用預先整合 SDK 的 HTML5 播放器,請查看 Video.js 專用的 IMA SDK 外掛程式。
IMA 用戶端簡介
實作 IMA 用戶端需要四個主要 SDK 元件,本指南會說明這些元件:
AdDisplayContainer
:容器物件,可指定 IMA 算繪廣告 UI 元素和評估可視度的所在位置,包括 Active View 和 Open Measurement。AdsLoader
:要求廣告的物件,並處理廣告請求回應中的事件。您應只例項化一個廣告載入器,這樣一來,您就能在整個應用程式生命週期中重複使用。AdsRequest
:定義廣告請求的物件。廣告要求會指定 VAST 廣告代碼的網址,以及其他參數,例如廣告尺寸。AdsManager
:包含廣告請求回應、控制廣告播放,以及聆聽 SDK 觸發的廣告事件的物件。
必要條件
在您開始之前,您需要擁有下列項目:
- 三個空白檔案:
- index.html
- style.css
- ads.js
- 電腦上已安裝 Python,或用於測試的網路伺服器
1. 啟動開發伺服器
由於 IMA SDK 會使用與載入頁面相同的通訊協定載入依附元件,因此您必須使用網路伺服器測試應用程式。啟動本機開發伺服器最簡單的方法,就是使用 Python 內建的伺服器。
- 使用指令列,從含有 index.html 檔案的目錄執行以下指令:
python -m http.server 8000
- 透過網路瀏覽器前往
http://localhost:8000/
您也可以使用任何其他網頁伺服器,例如 Apache HTTP Server。
2. 建立簡單的影片播放器
首先,請修改 index.html,建立簡單的 HTML5 影片元素,並在包裝元素中加入觸發播放的按鈕。以下範例會匯入 IMA SDK,並設定 AdDisplayContainer
容器元素。詳情請分別參閱「
匯入 IMA SDK
」和「
建立廣告容器
」兩個步驟。
新增必要的標記,以便載入 style.css 和 ads.js 檔案。接著,修改 styles.css,讓影片播放器在行動裝置上呈現回應式設計。最後,在 ads.js 中宣告變數,並在您點按播放按鈕時觸發影片播放。
請注意,ads.js 程式碼片段包含對 setUpIMA()
的呼叫,該呼叫在「
Initialize the AdsLoader and make an ads request
」一節中定義。
3. 匯入 IMA SDK
接著,請在 index.html 中使用指令碼標記新增 IMA 架構,放在 ads.js
的標記之前。
4. 建立廣告容器
在大多數瀏覽器中,IMA SDK 會使用專屬的廣告容器元素,同時顯示廣告和廣告相關的 UI 元素。這個容器的大小必須能從左上角疊加影片元素。adsManager
物件會設定放置在這個容器中的廣告的高度和寬度,因此您不需要手動設定這些值。
如要實作這個廣告容器元素,請先在 video-container
元素中建立新的 div
。接著,更新 CSS,將元素置於 video-element
的左上角。最後,請新增 createAdDisplayContainer()
函式,使用新的廣告容器 div
建立 AdDisplayContainer
物件。
5. 初始化 AdsLoader 並提出廣告請求
如要要求廣告,請建立 AdsLoader
例項。AdsLoader
建構函式會將 AdDisplayContainer
物件做為輸入內容,可用於處理與指定廣告代碼網址相關聯的 AdsRequest
物件。本例中使用的廣告代碼包含 10 秒的片頭廣告。您可以使用 IMA 影片套件檢查器測試這個或任何廣告代碼網址。
最佳做法是在網頁的整個生命週期中,只保留一個 AdsLoader
例項。如要提出其他廣告要求,請建立新的 AdsRequest
物件,但重複使用相同的 AdsLoader
。詳情請參閱 IMA SDK 常見問題。
使用 AdsLoader.addEventListener
監聽及回應廣告載入和錯誤事件。監聽下列事件:
ADS_MANAGER_LOADED
AD_ERROR
如要建立 onAdsManagerLoaded()
和 onAdError()
事件監聽器,請參閱下列範例:
6. 回應 AdsLoader 事件
AdsLoader
成功載入廣告時,會發出 ADS_MANAGER_LOADED
事件。剖析傳遞至回呼的事件,以便初始化 AdsManager
物件。AdsManager
會根據廣告代碼網址的回應,載入個別廣告。
請務必處理載入程序中發生的任何錯誤。如果廣告無法載入,請務必確保媒體播放作業在沒有廣告的情況下繼續進行,以免干擾使用者觀看內容。
如要進一步瞭解 onAdsManagerLoaded()
函式中設定的事件監聽器,請參閱以下子節:
處理 AdsManager
錯誤
為 AdsLoader
建立的錯誤處理程序也可以做為 AdsManager
的錯誤處理程序。請參閱事件處理常式,瞭解如何重複使用 onAdError()
函式。
處理播放和暫停事件
當 AdsManager
準備插入廣告以供顯示時,會觸發 CONTENT_PAUSE_REQUESTED
事件。處理這個事件時,請觸發對基礎影片播放器的暫停動作。同樣地,當廣告播放完畢時,AdsManager
會觸發 CONTENT_RESUME_REQUESTED
事件。如要處理這項事件,請重新啟動基礎內容影片的播放作業。
如需 onContentPauseRequested()
和 onContentResumeRequested()
函式的定義,請參閱以下範例:
處理非線性廣告期間的內容播放作業
AdsManager
會在廣告準備播放時暫停內容影片,但這項行為不適用於非線性廣告,因為在這種情況下,內容會在廣告顯示時繼續播放。
如要支援非線性廣告,請監聽 AdsManager
以發出 LOADED
事件。檢查廣告是否為線性廣告,如果不是,請在影片元素上恢復播放。
如要瞭解 onAdLoaded()
函式的定義,請參閱以下範例。
7. 在行動裝置上觸發點擊暫停功能
由於 AdContainer
會疊加影片元素,使用者無法直接與底層播放器互動。這可能會讓行動裝置使用者感到困惑,因為他們預期輕觸影片播放器即可暫停播放。為解決這個問題,IMA SDK 會將 IMA 未處理的任何點擊從廣告疊加層傳遞至 AdContainer
元素,以便處理這些點擊。這項規定不適用於非行動瀏覽器上的線性廣告,因為點按廣告會開啟點閱連結。
如要實作點按暫停功能,請在 on window load 事件監聽器中新增 adContainerClick()
點按處理常式函式。
8. 啟動 AdsManager
如要開始播放廣告,請啟動並開始 AdsManager
。如要全面支援行動瀏覽器,您無法自動播放廣告,請在使用者與網頁互動時觸發廣告播放,例如按下播放按鈕。
9. 支援調整播放器大小
如要讓廣告動態調整大小並配合影片播放器的大小,或配合螢幕方向變更,請在回應視窗大小調整事件時呼叫 adsManager.resize()
。
大功告成!您現在可以使用 IMA SDK 請求及顯示廣告。如要進一步瞭解其他進階 SDK 功能,請參閱其他指南或 GitHub 上的範例。