ערכות IMA SDK מאפשרות לכם לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. ערכות IMA SDK יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את הפעלת המודעות באפליקציות שלכם. בעזרת ערכות SDK בצד הלקוח של IMA, יש לך שליטה על הפעלת סרטונים בתוכן, בזמן שה-SDK מטפל בהפעלת המודעות. המודעות מופעלות נגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן של האפליקציה.
מדריך זה מדגים איך לשלב את IMA SDK באפליקציה פשוטה של נגן וידאו. אם רוצים לצפייה או לעקוב אחרי שילוב לדוגמה שהושלם, הורידו את דוגמה פשוטה מ-GitHub. אם אתם שמעוניינים בנגן HTML5 עם ערכת ה-SDK משולבת מראש, כדאי לבדוק את פלאגין של IMA SDK ל-Video.js.
סקירה כללית בצד הלקוח של IMA
ההטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמודגמים בתהליך guide:
AdDisplayContainer
: אובייקט מאגר תגים שבו מתבצעות מודעות.AdsLoader
: אובייקט ששולח מודעות ומטפל באירועים מתגובות לבקשות להצגת מודעות. צריך רק ליצור טוען מודעות אחד, שניתן להשתמש בו שוב במהלך חיי האפליקציה.AdsRequest
: אובייקט שמגדיר בקשה להצגת מודעות. בקשות להצגת מודעות מציינות את כתובת ה-URL של תג המודעה מסוג 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.
2. יצירת נגן וידאו פשוט
קודם כל, משנים את index.html כדי ליצור רכיב וידאו פשוט של HTML5, הכלול בתוך wrapping אלמנט וכדי להפעיל את הסרטון. הוסיפו גם את התגים הנחוצים כדי לטעון את קובצי style.css ו-ads.js. לאחר מכן, משנים את styles.css כדי ליצור את נגן הווידאו רספונסיביות למכשירים ניידים. לבסוף, ב-ads.js, צריך להפעיל את הסרטון בזמן ההפעלה לוחץ על הלחצן.
index.html!<doctype html >h<tml lang="en"<>/span> h<ead<>/span> t<itleI>MA HTML5 Simple Demo/<title > m<eta charset="utf-8"<>/span> m<eta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"<>/span> l<ink rel="stylesheet" href="style.css"<>/span> /<head > b<ody<>/span> d<iv id="page-content"<>/span> d<iv id="video-container"<>/span> v<ideo id="video-element"<>/span> s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"<>/span> s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"<>/span> /<video > /<div > b<utton id="play-button"P>lay/<button > /<div > s<cript src="ads.js"/><script > /<body >/<html >
#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%; }
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. צירוף רכיבי handler של דף ונגן וידאו
כדי לשנות את ההתנהגות של נגן הווידאו באמצעות 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 משתמש ברכיב ייעודי של מאגר מודעות כדי להציג גם מודעות וגם
רכיבים בממשק המשתמש שקשורים למודעות. גודל הקונטיינר הזה צריך להיות מתאים לשכבת-על של רכיב הווידאו
בפינה הימנית העליונה. הגובה והרוחב של המודעות הממוקמות במאגר הזה נקבעים לפי
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> ...
... #ad-container { position: absolute; top: 0; left: 0; width: 100%; }
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 של תג מודעה באמצעות
הכלי לבדיקת חבילת הווידאו של IMA.
מומלץ לתחזק רק מופע אחד של ima.AdsLoader
בכל רחבי
במחזור החיים של דף. כדי לשלוח בקשות נוספות להצגת מודעות, צריך ליצור 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. הפעלת Ads Manager
כדי להתחיל הפעלה של מודעה, צריך להפעיל את 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. הגדרת Ads Manager כרספונסיבי
כדי לוודא שגודל המודעות משתנה באופן דינמי כך שיתאים לגודל של נגן הווידאו, אם המסך
משנה את הגודל או הכיוון, האירוע של שינוי גודל החלון חייב להפעיל 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
גם מפעיל מספר אירועים שצריך לטפל בהם. האירועים האלה משמשים
כדי לעקוב אחר שינויי מצב, להפעיל הפעלה והשהיה בסרטון התוכן, ולרשום שגיאות.
טיפול בשגיאות
ה-handler של השגיאות שנוצר עבור AdsLoader
יכול לשמש כ-handler של השגיאות עבור
AdsManager
על ידי הוספת גורם מטפל חדש באירועים עם אותה פונקציית קריאה חוזרת.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); } ...
הפעלת אירועי הפעלה והשהיה
כשהAdsManager
מוכן להוסיף מודעה לרשת המדיה, הוא מפעיל את
אירוע 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
, שם ניתן להציג אותן
לטיפול. הכלל הזה לא רלוונטי למודעות לינאריות בדפדפנים שאינם ניידים, כי לחיצה על המודעה פותחת את
לחיצה על הקישור.
כדי להטמיע לחיצה להשהיה, צריך להוסיף רכיב handler של קליקים ל-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.