درخواست تبلیغات در محتوای فقط صوتی، درخواست تبلیغات در محتوای فقط صوتی

کیت توسعه نرم‌افزاری IMA HTML5 از تبلیغات صوتی با تنظیماتی مشابه تبلیغات ویدیویی پشتیبانی می‌کند، اما با چند تفاوت کلیدی. برای هر بخشی از تنظیمات IMA که در این راهنما پوشش داده نشده است، به راهنمای شروع به کار با HTML5 مراجعه کنید.

استفاده از تگ <audio> برای پخش محتوا

سازنده‌ی AdDisplayContainer یک آرگومان دوم به نام videoElement دریافت می‌کند که IMA آن را به عنوان پخش‌کننده‌ی محتوا ردیابی می‌کند. این آرگومان هم تگ <video> و هم تگ <audio> را می‌پذیرد. برای محتوای صوتی و تبلیغات، این راهنما استفاده از تگ <audio> را برای ساخت AdDisplayContainer توصیه می‌کند. اگر محتوای ویدیویی دارید، می‌توانید از تگ <video> برای نمایش ترکیبی از تبلیغات صوتی و تصویری استفاده کنید:

فهرست.html 

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

تبلیغات.js 

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

مخفی کردن AdDisplayContainer

کیت توسعه نرم‌افزار IMA HTML5 حتی اگر هیچ بخش نمایشی برای تبلیغات یا محتوا وجود نداشته باشد، همچنان به AdDisplayContainer نیاز دارد. به همین دلیل، توصیه می‌کنیم AdDisplayContainer را پنهان کنید. به مثالی از نحوه پنهان کردن عنصر مراجعه کنید:

استایل.css 

.ad-container {
  display: none;
}

کنترل‌های سفارشی

از آنجا که AdDisplayContainer پنهان است، برای مدیریت پخش در طول وقفه‌های تبلیغاتی به کنترل‌های سفارشی نیاز است. AdsManager متدهایی دارد که می‌توانند برای پیاده‌سازی این کنترل‌های سفارشی استفاده شوند:

مدیریت تبلیغات قابل رد شدن

از آنجا که هیچ AdDisplayContainer قابل مشاهده‌ای وجود ندارد، IMA SDK نمی‌تواند دکمه‌ی رد کردن تبلیغات را نمایش دهد. برای مدیریت تبلیغات قابل رد کردن، متدهای IMA زیر را پیاده‌سازی کنید:

نمونه کد زیر نحوه انجام این کار را نشان می‌دهد.

تبلیغات.js

شما می‌توانید یک تابع updateSkippable تنظیم کنید تا مشخص شود که آیا و چه زمانی می‌توان از یک تبلیغ صرف نظر کرد. این تابع باید در هر رویداد AD_PROGRESS IMA فراخوانی شود. برای راهنمایی در مورد نحوه تنظیم شنونده‌ها برای رویدادهای 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 با ما تماس بگیرید.