מודעות אודיו

IMA HTML5 SDK תומך במודעות אודיו עם הגדרה דומה לזו של מודעות וידאו, אבל כמה הבדלים מרכזיים. עבור כל חלק מהגדרת ה-IMA שלא מצוין במדריך זה, מומלץ לעיין במאמר תחילת העבודה ב-HTML5 guide.

שימוש ב<audio> תג להפעלת תוכן

ה-constructor של AdDisplayContainer משתמש בארגומנט שני בשם videoElement ש-IMA עוקב אחר התוכן שלו נגן. הארגומנט הזה מקבל גם תג <video> וגם תג <audio>. לאודיו תוכן ומודעות, מדריך זה ממליץ להשתמש בתג <audio> כדי ליצור AdDisplayContainer. אם יש לך תוכן וידאו, אפשר להשתמש בתג <video> כדי שמציגה שילוב של מודעות אודיו ומודעות וידאו:

index.html

<audio id="audio-player"></audio>
<div class="ad-container"></div>

ads.js

audioPlayer = document.getElementById('audio-player');
adContainer = document.getElementById('ad-container');
adDisplayContainer = new google.ima.AdDisplayContainer(adContainer,
audioPlayer);

הסתרת ה-AdDisplayContainer

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

style.css

.ad-container {
  display: none;
}

אמצעי בקרה בהתאמה אישית

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

• pause()
• resume()
• setVolume()

טיפול במודעות שניתן לדלג עליהן

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

• AdsManager.getAdSkippableState()
• AdEvent.getAdData()
• Ad.getSkipTimeOffset()

תוכלו להיעזר בקוד לדוגמה שלמטה כדי לבדוק איך לעשות את זה.

ads.js

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

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

  ...

  adsManager.addEventListener(
    google.ima.AdEvent.Type.AD_PROGRESS,
    onAdEvent);

  ...

}

function onAdEvent(adEvent) {
  const ad = adEvent.getAd();
  if (ad) {
    currentAd = ad; // currentAd is defined outside of this functions scope.
  }
  switch (adEvent.type) {

    ...

    case google.ima.AdEvent.Type.AD_PROGRESS:
      // See https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdProgressData
      const adProgressData = adEvent.getAdData();

      updateSkippable(
        adProgressData.currentTime,
        currentAd.getSkipTimeOffset()
      );
      break;
    ...

  }
}

/**
   * Called when there may be a change in the skippable state.
   * @param {number} currentTime The current time of the
   * currently playing ad.
   * @param {number} skipTimeOffset The number of seconds of playback
   * before the ad becomes skippable. -1 is returned for non skippable
   * ads or if this is unavailable.
   */
  updateSkippable(currentTime, skipTimeOffset) {
    const isAdSkippable = skipTimeOffset !== -1;
    const isSkipCurrentlyAllowed = adsManager.getAdSkippableState();
    const timeTillSkipInSeconds = Math.ceil(skipTimeOffset - currentTime);
    updateSkipUI(
        isAdSkippable, isSkipCurrentlyAllowed, timeTillSkipInSeconds);
  }

בשונה ממודעות וידאו, ב-IMA אין אפשרות לספק לחצן דילוג למודעות אודיו. המפתחים צריכים להוסיף ממשק משתמש מותאם אישית למודעות שניתן לדלג עליהן, והפעולה הזו מתבצעת באמצעות תג <button> פשוט. פונקציית updateSkipUI מעדכנת את לחצן הדילוג על סמך הקביעה אם המודעה ניתנת לדילוג, אם היא ניתנת כרגע לדילוג, כמה זמן נותר עד שהמודעה תהיה ניתנת לדילוג. הוא משתמש שיעור '.hidden', שאינו מסופק על ידי IMA. הכיתה .hidden מוסיפה display: none; אל <button>.

/**
 * Updates the skip button UI.
 * @param {boolean} isAdSkippable if the current ad is a skippable ad.
 * @param {boolean} isSkipCurrentlyAllowed if the ad can be skipped now.
 * @param {number} timeTillSkipInSeconds time until the ad can be skipped in
 * seconds.
 */
updateSkipUI(isAdSkippable, isSkipCurrentlyAllowed, timeTillSkipInSeconds) {
  if (isAdSkippable) {
    skipButton.classList.remove('hidden');
    if (isSkipCurrentlyAllowed) {
      skipButton.textContent = 'Skip ad';
      skipButton.disabled = false;
    } else {
      skipButton.textContent = `Skip in ${timeTillSkipInSeconds} seconds`;
      skipButton.disabled = true;
    }
  } else {
    skipButton.classList.add('hidden');
  }
}

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

skipButton.addEventListener('click', () => {
  adsManager.skip();
});

אלה השינויים העיקריים שנדרשים כדי להגדיר את IMA SDK עם מודעות אודיו. עבור לשאלות בנושא יישום, הפורום הטכני של IMA SDK.