ערכות ה-SDK של IMA מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. ערכות ה-SDK של IMA יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות ערכות SDK של IMA בצד הלקוח, אתם שומרים על השליטה בהפעלת הסרטונים של התוכן, בעוד ש-SDK מטפל בהפעלת המודעות. המודעות מופעלות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן באפליקציה.
במדריך הזה נסביר איך לשלב את IMA SDK באפליקציית נגן וידאו פשוטה. אם אתם רוצים לראות דוגמה לשילוב מלא או לפעול לפיה, תוכלו להוריד את הדוגמה הפשוטה מ-GitHub. אם אתם רוצים להשתמש בנגן HTML5 עם SDK משולב מראש, כדאי לבדוק את הפלאגין של IMA SDK ל-Video.js.
סקירה כללית על IMA מצד הלקוח
הטמעת IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמתוארים במדריך הזה:
AdDisplayContainer
: אובייקט מאגר שמציין איפה IMA מעבדת את רכיבי ממשק המשתמש של המודעות וממדידה את הניראות, כולל Active View ו-Open Measurement.AdsLoader
: אובייקט שמבקש מודעות ומטפל באירועים מתשובות לבקשות להצגת מודעות. צריך ליצור רק אובייקט אחד של Ads Loader, שאפשר להשתמש בו שוב במהלך חיי האפליקציה.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 Server.
2. יצירת נגן וידאו פשוט
קודם משנים את הקובץ index.html כדי ליצור רכיב וידאו פשוט של HTML5, שמכיל רכיב עטיפה וכפתור להפעלת ההפעלה. בדוגמה הבאה מייבאים את IMA SDK ומגדירים את רכיב הקונטיינר AdDisplayContainer
. פרטים נוספים זמינים בשלבים
ייבוא IMA SDK
ו
יצירת מאגר המודעות
.
מוסיפים את התגים הנדרשים כדי לטעון את הקבצים style.css ו-ads.js. לאחר מכן, משנים את הקובץ styles.css כדי להפוך את נגן הווידאו לרספונסיבי למכשירים ניידים. לבסוף, ב-ads.js, מגדירים את המשתנים ומפעילים את הפעלת הסרטון בלחיצה על לחצן ההפעלה.
שימו לב שקטע הקוד של ads.js מכיל קריאה ל-setUpIMA()
, שמוגדר בקטע
הפעלת AdsLoader ושליחת בקשה להצגת מודעות
.
3. ייבוא של IMA SDK
בשלב הבא, מוסיפים את מסגרת IMA באמצעות תג סקריפט ב-index.html, לפני התג של ads.js
.
4. יצירת מאגר המודעות
ברוב הדפדפנים, ה-IMA SDK משתמש באלמנט ייעודי של מאגר מודעות כדי להציג גם מודעות וגם אלמנטים של ממשק המשתמש שקשורים למודעות. הגודל של המארז הזה צריך להתאים לשכבה של רכיב הסרטון מהפינה הימנית העליונה. הגובה והרוחב של המודעות שממוקמות בקונטיינר הזה מוגדרים על ידי האובייקט adsManager
, כך שאין צורך להגדיר את הערכים האלה באופן ידני.
כדי להטמיע את הרכיב הזה של מאגר המודעות, קודם צריך ליצור רכיב div
חדש בתוך הרכיב video-container
. לאחר מכן, מעדכנים את קובץ ה-CSS כדי למקם את הרכיב בפינה הימנית העליונה של video-element
. לבסוף, מוסיפים את הפונקציה createAdDisplayContainer()
כדי ליצור את האובייקט AdDisplayContainer
באמצעות מאגר המודעות החדש div
.
5. איך מפעילים את AdsLoader ושולחים בקשה להצגת מודעות
כדי לבקש מודעות, צריך ליצור מכונה של AdsLoader
. ה-constructor של AdsLoader
מקבל אובייקט AdDisplayContainer
כקלט, וניתן להשתמש בו כדי לעבד אובייקטים מסוג AdsRequest
שמשויכים לכתובת URL של תג מודעה מסוים. תג המודעה שמוצג בדוגמה הזו מכיל מודעת Pre-roll באורך 10 שניות. אפשר לבדוק את כתובת ה-URL הזו של תג המודעה, או כל כתובת URL אחרת, באמצעות IMA Video Suite Inspector.
מומלץ לשמור רק על מופע אחד של AdsLoader
לכל מחזור החיים של הדף. כדי לשלוח בקשות נוספות להצגת מודעות, יוצרים אובייקט AdsRequest
חדש, אבל משתמשים שוב באותו AdsLoader
. מידע נוסף זמין בשאלות הנפוצות בנושא IMA SDK.
אפשר להשתמש ב-AdsLoader.addEventListener
כדי להמתין לאירועי שגיאה ולאירועים של מודעות טעונות ולהגיב להם.
מקשיבים לאירועים הבאים:
ADS_MANAGER_LOADED
AD_ERROR
כדי ליצור את המאזינים onAdsManagerLoaded()
ו-onAdError()
, אפשר לעיין בדוגמה הבאה:
6. תגובה לאירועים של AdsLoader
כשהמודעות נטענות בהצלחה ב-AdsLoader
, הוא פולט אירוע ADS_MANAGER_LOADED
. לנתח את האירוע שהוענק ל-callback כדי לאתחל את האובייקט AdsManager
. ה-AdsManager
טוען את המודעות הנפרדות כפי שמוגדרות בתגובה לכתובת ה-URL של תג המודעה.
חשוב לטפל בכל שגיאה שמתרחשת במהלך תהליך הטעינה. אם המודעות לא נטענות, חשוב לוודא שהפעלת המדיה ממשיכה ללא מודעות כדי למנוע הפרעה לצפייה של המשתמשים בתוכן.
מידע נוסף על המאזינים שמוגדרים בפונקציה onAdsManagerLoaded()
זמין בקטעים המשניים הבאים:
טיפול בשגיאות מסוג AdsManager
בורר השגיאות שנוצר ל-AdsLoader
יכול לשמש גם כבורר השגיאות של ה-AdsManager
. עיינו בקוד של פונקציית האירוע שמשתמשת שוב בפונקציה onAdError()
.
טיפול באירועי הפעלה והשהיה
כשה-AdsManager
מוכן להוסיף מודעה להצגה, הוא מפעיל את האירוע CONTENT_PAUSE_REQUESTED
. כדי לטפל באירוע הזה, מפעילים השהיה בנגן הווידאו הבסיסי. באופן דומה, כשמודעה מסתיימת, האירוע CONTENT_RESUME_REQUESTED
מופעל על ידי AdsManager
. כדי לטפל באירוע הזה, מפעילים מחדש את ההפעלה בסרטון התוכן הבסיסי.
ההגדרות של הפונקציות onContentPauseRequested()
ו-onContentResumeRequested()
מפורטות בדוגמה הבאה:
טיפול בהפעלת תוכן במהלך מודעות לא לינאריות
הקוד AdsManager
משהה את סרטון התוכן כשמודעה מוכנה להפעלה, אבל ההתנהגות הזו לא מתייחסת למודעות לא לינאריות, שבהן התוכן ממשיך לפעול בזמן שהמודעה מוצגת.
כדי לתמוך במודעות לא לינאריות, צריך להאזין ל-AdsManager
כדי שיפלוט את האירוע LOADED
. בודקים אם המודעה לינארית. אם לא, ממשיכים את ההפעלה של רכיב הווידאו.
ההגדרה של הפונקציה onAdLoaded()
מופיעה בדוגמה הבאה.
7. הפעלת האפשרות 'קליק להשהיה' במכשירים ניידים
מכיוון שה-AdContainer
מופיע כשכבת-על על אלמנט הווידאו, המשתמשים לא יכולים לבצע אינטראקציה ישירה עם הנגן הבסיסי. המצב הזה עלול לבלבל משתמשים במכשירים ניידים, שציפו שיוכלו להקיש על נגן הווידאו כדי להשהות את ההפעלה. כדי לטפל בבעיה הזו, IMA SDK מעביר את כל הקליקים שלא מטופלים על ידי IMA משכבת-העל של המודעה אל האלמנט AdContainer
, שבו אפשר לטפל בהם. השינוי הזה לא רלוונטי למודעות לינאריות בדפדפנים שאינם לנייד, כי לחיצה על המודעה פותחת את הקישור לקליק.
כדי להטמיע את האפשרות 'קליק להשהיה', מוסיפים את פונקציית הטיפול בקליק adContainerClick()
שנקראת ב-on window load listener.
8. הפעלת AdsManager
כדי להפעיל את ההפעלה של המודעה, מפעילים את האירוע AdsManager
. כדי לתמוך באופן מלא בדפדפנים לנייד, שבהם אי אפשר להפעיל מודעות באופן אוטומטי, כדאי להפעיל את הפעלת המודעות כתוצאה מאינטראקציות של משתמשים עם הדף, כמו לחיצה על לחצן ההפעלה.
9. תמיכה בשינוי הגודל של הנגן
כדי שהמודעות ישנו את הגודל באופן דינמי ויתאימו לגודל של נגן הווידאו, או כדי להתאים לשינויים בכיוון המסך, צריך להפעיל את adsManager.resize()
בתגובה לאירועים של שינוי גודל החלון.
זהו! עכשיו אתם שולחים בקשות למודעות ומציגים אותן באמצעות IMA SDK. למידע נוסף על תכונות מתקדמות יותר של ה-SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.