שליחת בקשה להצגת מודעות בתוכן אודיו בלבד

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

שימוש בתג <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

גם אם אין למודעות או לתוכן חלק שמוצג, עדיין נדרש 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 כדי לקבוע אם אפשר לדלג על מודעה ומתי. צריך להפעיל את הפונקציה הזו בכל AD_PROGRESSאירוע של IMA. הוראות להגדרת פונקציות event listener לאירועים של 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 עם מודעות אודיו. כדי לקבל תמיכה בבעיות שקשורות להטמעה, אפשר לפנות אלינו דרך מרכז העזרה של Ad Manager.