אוטומציה של פלייליסטים של מודעות

IMA HTML5 SDK תומך בפלייליסטים של מודעות אוטומטיים לחלוטין. התכונה הזו מוסיפה הפסקות למודעות לתוכן, כפי שצוין ב-Google Ad Manager, במהלך ניהול המודעות. בנוסף, הקוד של נגן הווידאו פשוט הרבה יותר, והוא נחוץ כדי לתמוך בהפסקות למודעות, כולל מודעות לפני סרטון (pre-roll), מודעות באמצע סרטון (mid-roll) ומודעות בסוף סרטון (post-roll).

• כשיוצרים את AdsManager, מעבירים אובייקט contentPlayback באמצעות הקריאה getAdsManager. לאובייקט הזה צריכה להיות תכונה currentTime שמחזירה את המיקום הנוכחי של פס ההפעלה בסרטון. אם אתם משתמשים ברכיב video של HTML5 כדי להציג את התוכן, תוכלו פשוט להעביר את הרכיב הזה ל-SDK. האובייקט הזה משמש למעקב אחר התקדמות ההפעלה של התוכן, כדי שהמערכת תוכל להוסיף הפסקות למודעות באופן אוטומטי במועדים שצוינו ב-Ad Manager. בנוסף, צריך להודיע ל-SDK שאתם רוצים שהוא יטפל במצב התוכן בשמכם.

  var adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoContent, adsRenderingSettings); // See API reference for contentPlayback.

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

  var videoContent = document.getElementById('contentElement');
  var contentEndedListener = function() {adsLoader.contentComplete();};
  
  videoContent.addEventListener('ended', contentEndedListener);
  
  function onContentPauseRequested() {
    contentElement.removeEventListener('ended', contentEndedListener);
    ...
  }
  
  function onContentResumeRequested() {
    contentElement.addEventListener('ended', contentEndedListener);
    ...
  }

• האירועים CONTENT_PAUSE_REQUESTED ו-CONTENT_RESUME_REQUESTED משמשים להשהיה ולהמשך של התוכן כשמוצגים הפסקות למודעות.
• אם נגן הווידאו תומך ב'גרירה כדי לדלג', ומאפיין הזמן הנוכחי של נגן הווידאו מתעדכן בזמן שהמשתמש גורר, ה-SDK לא יכול להבדיל בין תוכן שמתקדם באופן רגיל לבין משתמש שמדלג בתוכן. צריך להשתמש באובייקט contentPlayback בהתאמה אישית כפרמטר ל-getAdsManager. דוגמה לתרחיש לדוגמה הזה מופיעה במאמר הבעיה עם דילוג.

הערה: כשהתוכן מסתיים או שהמשתמש מפסיק את ההפעלה, חשוב להפעיל את AdsLoader.contentComplete כדי לסמן ל-SDK שהתוכן הסתיים. לאחר מכן, ה-SDK מפעיל את ההפסקה למודעות בסוף הסרטון, אם הוגדרה הפסקה כזו. האירוע ALL_ADS_COMPLETED מופעל אחרי שכל ההפסקות למודעות הושמעו. בנוסף, חשוב לזכור שתהליך המעקב אחר התוכן מתחיל כשמתבצעת קריאה ל-init(), ותמיד צריך לקרוא ל-init() לפני שמפעילים תוכן.

השבתת ההפעלה האוטומטית של הפסקות למודעות

בנסיבות מסוימות, יכול להיות שתרצו למנוע מ-SDK להפעיל הפסקות למודעות עד שתהיה לכם אפשרות להפעיל אותן. בתרחיש כזה, אפשר להשבית את ההפעלה האוטומטית של הפסקות למודעות ולהודיע ל-SDK מתי אתם מוכנים להפסקה למודעה. בהגדרה הזו, אחרי שה-SDK טוען הפסקה למודעה, הוא יוצר אירוע AD_BREAK_READY. כשהנגן מוכן לתחילת ההפסקה למודעה, אפשר להפעיל את adsManager.start():

function requestAds() {}
  ...
  adsLoader.getSettings().setAutoPlayAdBreaks(false);
  ...
}

function onAdsManagerLoaded() {
  ...
  // For non-auto ad breaks, listen for ad break ready
  adsManager.addEventListener(
      google.ima.AdEvent.Type.AD_BREAK_READY,
      adBreakReadyHandler);
  ...
}

function adBreakReadyHandler() {
  // Once we're ready to play ads. To skip this ad break, simply return
  // from this handler without calling adsManager.start().
  adsManager.start();
}

רוצה לנסות?

הקוד הבא מראה הטמעה עובדת.

הבעיה עם דילוג

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

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

הפתרון הזה מאפשר לדלג בצורה תקינה על הקליפ של 0:10 בסרטון, ולהפעיל רק את הקליפ של 0:20 בסרטון. כדי לעשות זאת, משתמשים במעקב אחר פס ההפעלה בהתאמה אישית בקטע הקוד הבא. הקוד הזה מכיל שינויים (מודגשים) של ads.js בדוגמה המתקדמת ל-HTML5 שזמינה בדף ההורדות שלנו.

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.videoPlayer_.contentPlayer.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

בעיות ידועות ב-Safari לנייד

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

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
  this.seeking = false;
  this.seekCheckInterval = 1000;
  // You may need to adjust this value, depending on your platform
  this.seekThreshold = 100;
  this.previousTime = 0;
  setInterval(
      Application.bind(this, this.checkForSeeking),
      this.seekCheckInterval);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.checkForSeeking = function() {
  var currentTime = this.videoPlayer_.contentPlayer.currentTime;
  // How much time has passed since you last ran this method, in milliseconds
  var diff = (currentTime - this.previousTime) * 1000;
  // If that difference is greater than the time since you last ran this method,
  // plus the threshold, the user was seeking
  if (Math.abs(diff)  > this.interval + this.threshold) {
    this.seeking = true;
  } else {
    this.seeking = false;
  }
  // Grab the current video time again to make up for time spent in this method
  previousTime = this.videoPlayer_.contentPlayer.currentTime;
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

בעקבות השינויים האלה, ערכת ה-SDK משתמשת עכשיו במאפיין currentTime של האובייקט Ads כדי לקבוע מתי להפעיל הפסקות למודעות, ולא במאפיין currentTime של נגן הסרטונים של התוכן.