IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปเป็นเรื่องง่าย IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่ สอดคล้องกับ VAST ใดๆ ก็ได้และจัดการการเล่นโฆษณาในแอปของคุณ เมื่อใช้ SDK ฝั่งไคลเอ็นต์ของ IMA คุณจะเป็นผู้ควบคุมการเล่นวิดีโอเนื้อหา ส่วน SDK จะจัดการการเล่นโฆษณา โฆษณาจะเล่นในโปรแกรมเล่นวิดีโอแยกต่างหากซึ่งอยู่ที่ด้านบนของโปรแกรมเล่นวิดีโอเนื้อหาของแอป
คู่มือนี้แสดงวิธีผสานรวม IMA SDK เข้ากับแอปโปรแกรมเล่นวิดีโอแบบง่าย หากคุณต้องการดูหรือทำตามตัวอย่างการผสานรวมที่สมบูรณ์ ให้ดาวน์โหลดตัวอย่างง่ายๆ จาก GitHub หากคุณสนใจโปรแกรมเล่น HTML5 ที่ผสานรวม SDK ไว้ล่วงหน้าแล้ว โปรดดูปลั๊กอิน IMA SDK สำหรับวิดีโอ.js
ภาพรวมฝั่งไคลเอ็นต์ของ IMA
การใช้งาน IMA ฝั่งไคลเอ็นต์นั้นเกี่ยวข้องกับองค์ประกอบ SDK หลัก 4 อย่างดังที่แสดงในคู่มือนี้
AdDisplayContainer
: คอนเทนเนอร์ออบเจ็กต์ที่แสดงโฆษณาAdsLoader
: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควรเตรียมตัวโหลดโฆษณาไว้เพียงตัวเดียว ซึ่งสามารถนำมาใช้ซ้ำได้ตลอดอายุของแอปพลิเคชันAdsRequest
: ออบเจ็กต์ที่กำหนดคำขอโฆษณา คำขอโฆษณาจะระบุ URL สำหรับแท็กโฆษณา VAST รวมถึงพารามิเตอร์เพิ่มเติม เช่น มิติข้อมูลโฆษณาAdsManager
: ออบเจ็กต์ที่มีการตอบกลับคำขอโฆษณา ควบคุมการเล่นโฆษณา และรอฟังเหตุการณ์โฆษณาที่ SDK เริ่มทำงาน
ข้อกำหนดเบื้องต้น
ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้
- ไฟล์เปล่า 3 ไฟล์ ได้แก่
- index.html
- style.css
- ads.js
- Python ที่ติดตั้งในคอมพิวเตอร์หรือเว็บเซิร์ฟเวอร์ที่จะใช้ในการทดสอบ
1. เริ่มต้นเซิร์ฟเวอร์การพัฒนา
เนื่องจาก IMA SDK โหลดทรัพยากร Dependency ผ่านโปรโตคอลเดียวกับหน้าเว็บที่โหลด คุณต้องใช้เว็บเซิร์ฟเวอร์ในการทดสอบแอป วิธีที่ง่ายที่สุดในการเริ่มต้นเซิร์ฟเวอร์การพัฒนาภายในคือการใช้เซิร์ฟเวอร์ในตัวของ Python
- การใช้บรรทัดคำสั่งจากไดเรกทอรีที่มีไฟล์ index.html ที่เรียกใช้
python -m http.server 8000
- ในเว็บเบราว์เซอร์ ให้ไปที่
http://localhost:8000/
คุณยังใช้เว็บเซิร์ฟเวอร์อื่น เช่น เซิร์ฟเวอร์ Apache HTTP ได้ด้วย
2. สร้างโปรแกรมเล่นวิดีโอง่ายๆ
ก่อนอื่นให้แก้ไข index.html เพื่อสร้างองค์ประกอบวิดีโอ HTML5 แบบง่ายที่มีอยู่ในองค์ประกอบการตัดข้อความและปุ่มสำหรับเล่น และเพิ่มแท็กที่จําเป็นเพื่อโหลดไฟล์ style.css และ ads.js ด้วย จากนั้นแก้ไข styles.css เพื่อให้โปรแกรมเล่นวิดีโอตอบสนองต่ออุปกรณ์เคลื่อนที่ สุดท้าย ใน ads.js ให้ทริกเกอร์การเล่นวิดีโอเมื่อมีการคลิกปุ่มเล่น
index.html<!doctype html> <html lang="en"> <head> <title>IMA HTML5 Simple Demo</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="stylesheet" href="style.css"> </head> <body> <div id="page-content"> <div id="video-container"> <video id="video-element"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> </div> <button id="play-button">Play</button> </div> <script src="ads.js"></script> </body> </html>style.css
#page-content { position: relative; /* this element's width controls the effective height */ /* of the video container's padding-bottom */ max-width: 640px; margin: 10px auto; } #video-container { position: relative; /* forces the container to match a 16x9 aspect ratio */ /* replace with 75% for a 4:3 aspect ratio, if needed */ padding-bottom: 56.25%; } #video-element { /* forces the contents to fill the container */ position: absolute; top: 0; left: 0; width: 100%; height: 100%; }ads.js
var videoElement; // On window load, attach an event to the play button click // that triggers playback on the video element window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); });
หลังจากทำขั้นตอนนี้เสร็จแล้ว เมื่อเปิด index.html ในเบราว์เซอร์ (ผ่านเซิร์ฟเวอร์การพัฒนา) คุณควรจะเห็นองค์ประกอบวิดีโอและควรเริ่มเล่นวิดีโอเมื่อคลิกปุ่มเล่น
3. นำเข้า IMA SDK
จากนั้นเพิ่มเฟรมเวิร์ก IMA โดยใช้แท็กสคริปต์ใน index.html ก่อนแท็กของ
ads.js
... </video> </div> <button id="play-button">Play</button> </div> <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script> <script src="ads.js"></script> </body> </html>
4. แนบหน้าและเครื่องจัดการโปรแกรมเล่นวิดีโอ
หากต้องการแก้ไขลักษณะการทำงานของโปรแกรมเล่นวิดีโอที่มี JavaScript ให้เพิ่มเครื่องจัดการเหตุการณ์ที่ทริกเกอร์การดำเนินการต่อไปนี้
- เมื่อโหลดหน้าเว็บเสร็จแล้ว ให้เริ่มต้น IMA SDK
- เมื่อมีการคลิกปุ่มเล่นวิดีโอ ให้โหลดโฆษณา (เว้นแต่มีการโหลดโฆษณาไว้แล้ว)
- เมื่อปรับขนาดหน้าต่างเบราว์เซอร์ ให้อัปเดตองค์ประกอบวิดีโอและขนาด
adsManager
เพื่อทำให้หน้าเว็บปรับเปลี่ยนตามอุปกรณ์สำหรับอุปกรณ์เคลื่อนที่
var videoElement; // Define a variable to track whether there are ads loaded and initially set it to false var adsLoaded = false; window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); initializeIMA(); videoElement.addEventListener('play', function(event) { loadAds(event); }); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); }); window.addEventListener('resize', function(event) { console.log("window resized"); }); function initializeIMA() { console.log("initializing IMA"); } function loadAds(event) { // Prevent this function from running on if there are already ads loaded if(adsLoaded) { return; } adsLoaded = true; // Prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); }
5. สร้างคอนเทนเนอร์โฆษณา
ในเบราว์เซอร์ส่วนใหญ่ IMA SDK ใช้องค์ประกอบคอนเทนเนอร์โฆษณาโดยเฉพาะเพื่อแสดงทั้งโฆษณาและองค์ประกอบ UI ที่เกี่ยวข้องกับโฆษณา คอนเทนเนอร์นี้ต้องมีขนาดเพื่อวางซ้อนองค์ประกอบวิดีโอจากมุมซ้ายบน ความสูงและความกว้างของโฆษณาที่วางในคอนเทนเนอร์นี้กำหนดโดยออบเจ็กต์ adsManager
คุณจึงไม่ต้องตั้งค่าเหล่านี้ด้วยตนเอง
หากต้องการใช้องค์ประกอบคอนเทนเนอร์โฆษณานี้ ให้สร้าง div
ใหม่ภายในองค์ประกอบ video-container
ก่อน จากนั้นอัปเดต CSS ให้วางองค์ประกอบที่มุมบนซ้ายของ video-element
สุดท้าย ให้กำหนดตัวแปรสำหรับคอนเทนเนอร์ภายในฟังก์ชัน initializeIMA()
ที่ทำงานเมื่อหน้าเว็บโหลด
... <div id="video-container"> <video id="video-element" controls> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> <div id="ad-container"></div> </div> ...style.css
... #ad-container { position: absolute; top: 0; left: 0; width: 100%; }ads.js
var videoElement; var adsLoaded = false; var adContainer; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); }
6. เริ่มต้น AdsLoader และสร้างคำขอโฆษณา
หากต้องการขอชุดโฆษณา ให้สร้างอินสแตนซ์ ima.AdsLoader
อินสแตนซ์นี้รับออบเจ็กต์ AdDisplayContainer
เป็นอินพุต และสามารถใช้ในการประมวลผลออบเจ็กต์ ima.AdsRequest
ที่เชื่อมโยงกับ URL แท็กโฆษณาที่ระบุ แท็กโฆษณาที่ใช้ในตัวอย่างนี้มีโฆษณาตอนต้นความยาว 10 วินาที คุณสามารถทดสอบ URL ของแท็กโฆษณานี้หรือ URL ของแท็กโฆษณาได้โดยใช้
IMA Video Suite Inspector
แนวทางปฏิบัติแนะนำคือให้คง ima.AdsLoader
ไว้เพียง 1 อินสแตนซ์ตลอดอายุการใช้งานหน้าเว็บ หากต้องการส่งคำขอโฆษณาเพิ่มเติม ให้สร้างออบเจ็กต์ ima.AdsRequest
ใหม่ แต่ใช้ ima.AdsLoader
เดิมซ้ำ ดูข้อมูลเพิ่มเติมได้ในคำถามที่พบบ่อยเกี่ยวกับ IMA SDK
var videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); // Let the AdsLoader know when the video has ended videoElement.addEventListener('ended', function() { adsLoader.contentComplete(); }); var adsRequest = new google.ima.AdsRequest(); adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' + 'iu=/21775744923/external/single_ad_samples&sz=640x480&' + 'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' + 'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='; // Specify the linear and nonlinear slot sizes. This helps the SDK to // select the correct creative if multiple are returned. adsRequest.linearAdSlotWidth = videoElement.clientWidth; adsRequest.linearAdSlotHeight = videoElement.clientHeight; adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth; adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3; // Pass the request to the adsLoader to request ads adsLoader.requestAds(adsRequest); }
7. ฟังเหตุการณ์ AdsLoader
เมื่อโฆษณาโหลดเรียบร้อยแล้ว ima.AdsLoader
จะปล่อยเหตุการณ์ ADS_MANAGER_LOADED
แยกวิเคราะห์เหตุการณ์ที่ส่งไปยังโค้ดเรียกกลับเพื่อเริ่มต้นออบเจ็กต์ AdsManager
AdsManager
จะโหลดโฆษณาแต่ละรายการตามที่กำหนดโดยการตอบกลับ URL แท็กโฆษณา
นอกจากนี้ โปรดจัดการข้อผิดพลาดที่อาจเกิดขึ้นระหว่างกระบวนการโหลดด้วย หากโฆษณาไม่โหลด ให้ตรวจสอบว่าการเล่นสื่อดำเนินต่อไปโดยไม่มีโฆษณา เพื่อไม่ให้รบกวนประสบการณ์ของผู้ใช้
ads.jsvar videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; var adsManager; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); adsLoader.addEventListener( google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED, onAdsManagerLoaded, false); adsLoader.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false); ... function onAdsManagerLoaded(adsManagerLoadedEvent) { // Instantiate the AdsManager from the adsLoader response and pass it the video element adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); } function onAdError(adErrorEvent) { // Handle the error logging. console.log(adErrorEvent.getError()); if(adsManager) { adsManager.destroy(); } }
8. เริ่มต้น AdsManager
หากต้องการเริ่มเล่นโฆษณา คุณต้องเริ่มเล่น AdsManager
ควรทริกเกอร์โดยการโต้ตอบของผู้ใช้เพื่อรองรับเบราว์เซอร์ในอุปกรณ์เคลื่อนที่อย่างเต็มรูปแบบ
... function loadAds(event) { // prevent this function from running on every play event if(adsLoaded) { return; } adsLoaded = true; // prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); // Initialize the container. Must be done via a user action on mobile devices. videoElement.load(); adDisplayContainer.initialize(); var width = videoElement.clientWidth; var height = videoElement.clientHeight; try { adsManager.init(width, height, google.ima.ViewMode.NORMAL); adsManager.start(); } catch (adError) { // Play the video without ads, if an error occurs console.log("AdsManager could not be started"); videoElement.play(); } } ...
9. ทำให้ AdsManager ปรับเปลี่ยนตามอุปกรณ์
หากหน้าจอเปลี่ยนขนาดหรือการวางแนว เหตุการณ์การปรับขนาดหน้าต่างจะต้องเรียกใช้ adsManager.resize()
เพื่อให้แน่ใจว่าโฆษณาจะปรับขนาดแบบไดนามิกให้ตรงกับขนาดโปรแกรมเล่นวิดีโอ
... window.addEventListener('resize', function(event) { console.log("window resized"); if(adsManager) { var width = videoElement.clientWidth; var height = videoElement.clientHeight; adsManager.resize(width, height, google.ima.ViewMode.NORMAL); } }); ...
10. ฟังเหตุการณ์ของ AdsManager
นอกจากนี้ AdsManager
ยังเริ่มการทำงานของหลายเหตุการณ์ที่ต้องจัดการด้วย เหตุการณ์เหล่านี้ใช้เพื่อติดตามการเปลี่ยนแปลงสถานะ ทริกเกอร์การเล่นและหยุดชั่วคราวในวิดีโอเนื้อหา และบันทึกข้อผิดพลาด
การจัดการข้อผิดพลาด
ตัวแฮนเดิลข้อผิดพลาดที่สร้างขึ้นสำหรับ AdsLoader
ทำหน้าที่เป็นตัวแฮนเดิลข้อผิดพลาดสำหรับ AdsManager
ได้ด้วยการเพิ่มเครื่องจัดการเหตุการณ์ใหม่ที่มีฟังก์ชันเรียกกลับเดียวกัน
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); } ...
การทริกเกอร์เหตุการณ์เล่นและหยุดชั่วคราว
เมื่อ AdsManager
พร้อมแทรกโฆษณาสําหรับ Display เหตุการณ์ CONTENT_PAUSE_REQUESTED
จะเริ่มทํางาน โปรดจัดการเหตุการณ์นี้ด้วยการทริกเกอร์การหยุดชั่วคราวในโปรแกรมเล่นวิดีโอที่เกี่ยวข้อง ในทำนองเดียวกัน เมื่อโฆษณาเสร็จสมบูรณ์ เหตุการณ์ AdsManager
จะทำให้เหตุการณ์ CONTENT_RESUME_REQUESTED
เริ่มทำงาน โปรดจัดการเหตุการณ์นี้โดยการเริ่มเล่นวิดีโอในเนื้อหาที่เกี่ยวข้องอีกครั้ง
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); } ... function onContentPauseRequested() { videoElement.pause(); } function onContentResumeRequested() { videoElement.play(); }
การทริกเกอร์การคลิกเพื่อหยุดชั่วคราวบนอุปกรณ์เคลื่อนที่
เนื่องจาก AdContainer
ซ้อนทับองค์ประกอบวิดีโอ ผู้ใช้จึงโต้ตอบกับโปรแกรมเล่นที่อยู่เบื้องหลังโดยตรงไม่ได้ ซึ่งอาจทำให้ผู้ใช้อุปกรณ์เคลื่อนที่สับสนว่าจะต้องแตะโปรแกรมเล่นวิดีโอเพื่อหยุดเล่นชั่วคราว ในการแก้ปัญหานี้ IMA SDK จะส่งคลิกที่ IMA ไม่ได้จัดการจากการวางซ้อนโฆษณาไปยังองค์ประกอบ AdContainer
ซึ่งสามารถจัดการได้ แต่ไม่ได้ใช้กับโฆษณาเชิงเส้นในเบราว์เซอร์ที่ไม่ใช่อุปกรณ์เคลื่อนที่ เนื่องจากการคลิกโฆษณาจะเปิด
ลิงก์การคลิกผ่าน
หากต้องการใช้การคลิกเพื่อหยุดชั่วคราว ให้เพิ่มเครื่องจัดการการคลิกลงใน AdContainer
และเรียกใช้การเล่นหรือหยุดเหตุการณ์ชั่วคราวในวิดีโอต้นฉบับ
... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adContainer.addEventListener('click', adContainerClick); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); ... function adContainerClick(event) { console.log("ad container clicked"); if(videoElement.paused) { videoElement.play(); } else { videoElement.pause(); } } ...
การทริกเกอร์ให้เล่นโฆษณาที่ปรากฏร่วมกับวิดีโอ
AdsManager
จะหยุดวิดีโอเนื้อหาไว้ชั่วคราวเมื่อโฆษณาพร้อมเล่น แต่ลักษณะการทำงานนี้ไม่ได้รวมถึงโฆษณาที่ไม่ใช่เชิงเส้น ซึ่งเนื้อหาควรเล่นต่อไปขณะแสดงโฆษณา หากต้องการรองรับโฆษณาที่ไม่ใช่เชิงเส้น ให้รอฟัง AdsManager
เพื่อปล่อยเหตุการณ์ LOADED
จากนั้น ให้ตรวจสอบว่าโฆษณาเป็นแบบเชิงเส้นหรือไม่ หากไม่ใช่ ให้เล่นต่อในองค์ประกอบวิดีโอ
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); adsManager.addEventListener( google.ima.AdEvent.Type.LOADED, onAdLoaded); } ... function onAdLoaded(adEvent) { var ad = adEvent.getAd(); if (!ad.isLinear()) { videoElement.play(); } }
เท่านี้ก็เรียบร้อย คุณกำลังขอและแสดงโฆษณาด้วย IMA SDK หากต้องการดูข้อมูลเกี่ยวกับฟีเจอร์ SDK ขั้นสูงเพิ่มเติม โปรดดูคำแนะนำอื่นๆ หรือตัวอย่างใน GitHub