تبلیغات صوتی

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 را تنظیم کنید تا مشخص کنید آیا می‌توان از یک تبلیغ صرفنظر کرد یا نه. این تابع باید در هر رویداد 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/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 مراجعه کنید.