אני רוצה לנסות

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

  1. באמצעות שורת פקודה, מהספרייה שמכילה הרצת הקובץ index.html: 
      python -m http.server 8000
  2. בדפדפן אינטרנט, עוברים אל 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
>
 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. צירוף רכיבי handler של דף ונגן וידאו

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

מומלץ לתחזק רק מופע אחד של 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

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

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. הגדרת Ads Manager כרספונסיבי

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

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

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

ads.js 
...

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

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

...

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

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

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

כדי להטמיע לחיצה להשהיה, צריך להוסיף רכיב handler של קליקים ל-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.