מודעות אודיו

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

ל-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');
  }
}

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

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

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