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

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

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

3. ייבוא של IMA SDK

בשלב הבא, מוסיפים את מסגרת IMA באמצעות תג סקריפט ב-index.html, לפני התג של ads.js.

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

ברוב הדפדפנים, ה-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. ה-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(), אפשר לעיין בדוגמה הבאה:

/**
 * 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&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 = 640;
  adsRequest.linearAdSlotHeight = 400;

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

  adsLoader.requestAds(adsRequest);
}ads.js

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

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

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

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

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

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

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() שנקראת ב-on window load listener.

/**
 * 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.