מתחילים

ערכות ה-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.

  1. משורת הפקודה, בתיקייה שמכילה את קובץ ה-index.html, מריצים את הפקודה: 
      python -m http.server 8000
  2. בדפדפן אינטרנט, עוברים אל http://localhost:8000/

אפשר גם להשתמש בכל שרת אינטרנט אחר, כמו Apache HTTP Server.

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.

index.html 
...

        </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 כדי שהדף יהיה רספונסיבי במכשירים ניידים
ads.js 
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() שפועלת כשהדף נטען.

index.html 
...

  <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 של תג מודעה מסוימת. תג המודעה שמוצג בדוגמה הזו מכיל מודעת Pre-roll באורך 10 שניות. אפשר לבדוק את כתובת ה-URL הזו של תג המודעה, או כל כתובת URL אחרת, באמצעות IMA Video Suite Inspector.

מומלץ לשמור רק על מופע אחד של ima.AdsLoader לכל מחזור החיים של הדף. כדי לשלוח בקשות נוספות להצגת מודעות, יוצרים אובייקט ima.AdsRequest חדש, אבל משתמשים שוב באותו ima.AdsLoader. מידע נוסף זמין בשאלות הנפוצות בנושא IMA SDK.

ads.js 
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

כשהמודעות נטענות בהצלחה, האירוע ADS_MANAGER_LOADED מופעל על ידי ima.AdsLoader. לנתח את האירוע שהוענק ל-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. הפעלת AdsManager

כדי להפעיל את ההפעלה של המודעה, צריך להפעיל את AdsManager. כדי לתמוך באופן מלא בדפדפנים לנייד, צריך להפעיל את הקוד הזה כתגובה לאינטראקציה של המשתמש.

ads.js 
...

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().

ads.js 
...

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 מפעיל גם כמה אירועים שצריך לטפל בהם. האירועים האלה משמשים למעקב אחרי שינויים במצב, להפעלת הפעלה והשהיה בסרטון התוכן ולרישום שגיאות.

טיפול בשגיאות

אפשר להוסיף בורר אירועים חדש עם אותה פונקציית קריאה חוזרת (callback) כדי שבורר השגיאות שנוצר ל-AdsLoader ישמש גם ל-AdsManager.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

הפעלת אירועי הפעלה והשהיה

כשה-AdsManager מוכן להוסיף מודעה להצגה, הוא מפעיל את האירוע CONTENT_PAUSE_REQUESTED. כדי לטפל באירוע הזה, מפעילים השהיה בנגן הווידאו הבסיסי. באופן דומה, כשמודעה מסתיימת, האירוע CONTENT_RESUME_REQUESTED מופעל על ידי AdsManager. כדי לטפל באירוע הזה, מפעילים מחדש את ההפעלה בסרטון התוכן הבסיסי.

ads.js 
...

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 ומפעילים אירועי הפעלה או השהיה בסרטון הבסיסי.

ads.js 
...

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. לאחר מכן, בודקים אם המודעה לינארית. אם לא, ממשיכים את ההפעלה של רכיב הווידאו.

ads.js 
...

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.