מודעות אודיו

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

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

למבנה 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

עדיין נדרש AdDisplayContainer ב-IMA HTML5 SDK גם אם אין קטע תצוגה במודעות או בתוכן. לכן מומלץ להסתיר את 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/interface/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.