דף זה תורגם על ידי Cloud Translation API.

שנתחיל?

באמצעות ערכות ה-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.server זמין רק ב-Python 3.x.
בדפדפן האינטרנט, נכנסים אל http://localhost:8000/

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

2. יצירת נגן וידאו פשוט

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

כדי לשנות את אופן הפעולה של נגן הווידאו באמצעות JavaScript, מוסיפים רכיבי handler של אירועים שגורמים לפעולות הבאות:

לאחר טעינת הדף, מפעילים את 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");
}

ברוב הדפדפנים, 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 של וידאו.

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

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

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

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

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

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.

שנתחיל?

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

דרישות מוקדמות

1. הפעלת שרת פיתוח

2. יצירת נגן וידאו פשוט

3. ייבוא IMA SDK

4. יש לצרף רכיבי handler של דפים ונגני וידאו

5. יצירה של מאגר מודעות

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

7. האזנה לאירועים של AdsLoader

8. הפעלת Ads Manager

9. הגדרת תגובה של AdsManager

10. האזנה לאירועים של AdsManager

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

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

הקפצה של לחיצה להשהיה במכשירים ניידים

הפעלת מודעות במודעות לא לינאריות