בעזרת ערכות ה-IMA SDK אפשר לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. IMA SDK יכול לבקש הצגה של מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את הפעלת המודעות באפליקציות שלך. ערכות SDK בצד הלקוח של IMA מאפשרת לך לשלוט בהפעלת הסרטונים בתוכן, וה-SDK מטפל בהפעלת המודעות. המודעות מופעלות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של תוכן האפליקציה.
במדריך הזה נדגים איך לשלב את ה-IMA SDK באפליקציה פשוטה של נגן וידאו. אם אתם רוצים להציג את השילוב לדוגמה שהושלם, או לעקוב אחריו, תוכלו להוריד את הדוגמה הפשוטה מ-GitHub. אם אתה רוצה להשתמש בנגן HTML5 עם הטמעה מראש של ה-SDK, מומלץ לעיין בפלאגין של IMA SDK ל-Video.js.
סקירה כללית בצד הלקוח של IMA
ההטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, כפי שמתואר במדריך הזה:
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/
אפשר גם להשתמש בכל שרת אינטרנט אחר, כמו שרת ה-HTTP Apache.
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. צירוף רכיבי 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>
...
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 למשך כל מחזור החיים של דף. כדי לשלוח בקשות נוספות להצגת מודעות, צריך ליצור אובייקט 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. ניתוח האירוע שהועבר לקריאה החוזרת (callback) כדי לאתחל את האובייקט AdsManager. השדה AdsManager טוען את המודעות הנפרדות, כפי שהוגדר בתגובה לכתובת ה-URL של תג המודעה.
בנוסף, יש להקפיד לטפל בכל השגיאות שעשויות להתרחש במהלך הטעינה. אם המודעות לא נטענות, צריך לוודא שהפעלת מדיה נמשכת, ללא מודעות, כדי לא להפריע לחוויית המשתמש.
ads.js
var 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 מופעלים כמה אירועים שצריך לטפל בהם. האירועים האלה משמשים
למעקב אחר שינויים במצב, להפעלה ולהשהיה של תוכן בסרטון ולרישום שגיאות.
טיפול בשגיאות
הגורם המטפל בשגיאות שנוצר עבור 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, שבו ניתן לטפל בהם. כלל זה לא חל על מודעות לינאריות בדפדפנים שאינם לנייד, שכן לחיצה על המודעה פותחת את קישור הקליקים.
כדי להטמיע click-to-pause, מוסיפים את ה-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.