הגדרת IMA SDK

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ‫IMA SDKs יכולים לשלוח בקשות למודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. עם IMA SDK בצד הלקוח, אתם שומרים על שליטה בהפעלת תוכן הווידאו, בזמן שה-SDK מטפל בהפעלת המודעה. המודעות מוצגות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן באפליקציה.

במדריך הזה מוסבר איך לשלב את IMA SDK באפליקציית נגן וידאו פשוטה. אם אתם רוצים לראות או לעקוב אחרי שילוב לדוגמה, אתם יכולים להוריד את הדוגמה הפשוטה מ-GitHub. אם אתם מעוניינים בנגן HTML5 עם SDK שמשולב מראש, כדאי לעיין בפלאגין IMA SDK ל-Video.js.

סקירה כללית על IMA בצד הלקוח

הטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמוסברים במדריך הזה:

  • ‫ AdDisplayContainer: אובייקט מאגר שמציין איפה IMA מעבד רכיבי ממשק משתמש של מודעות ומודד את הניראות, כולל Active View ו-Open Measurement.
  • ‫ AdsLoader: אובייקט שמבקש מודעות ומטפל באירועים מתגובות לבקשות מודעות. צריך ליצור רק מופע אחד של הכלי להעלאת מודעות, שאפשר להשתמש בו שוב לאורך חיי האפליקציה.
  • ‫ 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, שכלול ברכיב עוטף, ולחצן להפעלת הסרטון. בדוגמה הבאה, מייבאים את IMA SDK ומגדירים את רכיב הקונטיינר AdDisplayContainer. פרטים נוספים זמינים בשלבים ייבוא IMA SDK ו יצירת מאגר המודעות . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

מוסיפים את התגים הנדרשים לטעינת הקבצים style.css ו-ads.js. לאחר מכן, משנים את הקובץ styles.css כדי שהנגן יהיה רספונסיבי בניידים. לבסוף, בקובץ ads.js, מגדירים את המשתנים ומפעילים את הפעלת הסרטון כשלוחצים על לחצן ההפעלה.

שימו לב שקטע הקוד ads.js מכיל קריאה ל-setUpIMA(), שמוגדרת בקטע Initialize the AdsLoader and make an ads request .

3. ייבוא של IMA SDK

לאחר מכן, מוסיפים את מסגרת IMA באמצעות תג script בקובץ index.html, לפני התג של ads.js. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. יצירת קונטיינר המודעות

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

כדי להטמיע את רכיב מאגר המודעות הזה, קודם צריך ליצור רכיב div חדש בתוך הרכיב video-container. לאחר מכן, מעדכנים את ה-CSS כדי למקם את הרכיב בפינה הימנית העליונה של video-element. לבסוף, מוסיפים את הפונקציה createAdDisplayContainer() כדי ליצור את האובייקט AdDisplayContainer באמצעות מאגר המודעות החדש div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. מאתחלים את AdsLoader ושולחים בקשה להצגת מודעות

כדי לבקש מודעות, צריך ליצור מופע של AdsLoader. הקונסטרוקטור AdsLoader מקבל אובייקט AdDisplayContainer כקלט, ואפשר להשתמש בו כדי לעבד אובייקטים מסוג AdsRequest שמשויכים לכתובת URL של תג מודעה שצוינה. תג המודעה שמשמש בדוגמה הזו מכיל מודעה שלפני הסרטון באורך 10 שניות. אתם יכולים לבדוק את כתובת ה-URL הזו של תג המודעה, או כל כתובת URL אחרת של תג מודעה, באמצעות IMA Video Suite Inspector.

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

אתם יכולים להמתין לאירועים של טעינת מודעות ושגיאות ולהגיב להם באמצעות AdsLoader.addEventListener. האזנה לאירועים הבאים:

  • ADS_MANAGER_LOADED
  • AD_ERROR

כדי ליצור את רכיבי ה-listener‏ onAdsManagerLoaded() ו-onAdError(), אפשר לעיין בדוגמה הבאה: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. תגובה לאירועים של AdsLoader

כשהרכיב AdsLoader טוען מודעות בהצלחה, הוא פולט אירוע ADS_MANAGER_LOADED. מנתחים את האירוע שמועבר לקריאה החוזרת כדי לאתחל את האובייקט AdsManager. ‫AdsManager טוען את המודעות הבודדות כפי שהן מוגדרות בתגובה לכתובת ה-URL של תג המודעה.

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

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

לפרטים נוספים על הפונקציה onAdsManagerLoaded(), אפשר לעיין בקטעי המשנה הבאים:

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

ה-error handler שנוצר עבור AdsLoader יכול לשמש גם כ-error handler עבור AdsManager. אפשר לראות את המטפל באירועים שמשתמש מחדש בפונקציה onAdError(). 

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

טיפול באירועי הפעלה והשהיה

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

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

הגדרות של הפונקציות onContentPauseRequested() ו-onContentResumeRequested() מופיעות בדוגמה הבאה: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

טיפול בהפעלת תוכן במהלך מודעות לא לינאריות

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

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

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

הגדרה של הפונקציה onAdLoaded() מופיעה בדוגמה הבאה. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. הפעלת קליק להשהיה במכשירים ניידים

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

כדי להטמיע את התכונה 'קליק להשהיה', מוסיפים את adContainerClick() פונקציית הטיפול בקליקים שנקראת במאזין לטעינת החלון. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. הפעלת AdsManager

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

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. תמיכה בשינוי הגודל של הנגן

כדי שהמודעות ישנו את הגודל שלהן באופן דינמי בהתאם לגודל של נגן הווידאו, או בהתאם לשינויים בכיוון המסך, צריך לקרוא ל-adsManager.resize() בתגובה לאירועי שינוי הגודל של החלון. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

זהו! עכשיו אתם שולחים בקשות למודעות ומציגים אותן באמצעות IMA SDK. כדי לקבל מידע על תכונות מתקדמות נוספות של SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.