طلب عرض الإعلانات على المحتوى الصوتي فقط

تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية بتنسيق HTML5 مع الإعلانات الصوتية التي تتضمّن إعدادًا مشابهًا لإعلانات الفيديو، ولكن مع بعض الاختلافات الأساسية. للحصول على معلومات حول أي جزء من عملية إعداد "إعلانات الوسائط التفاعلية" لم يتم تناوله في هذا الدليل، يُرجى الاطّلاع على دليل البدء في 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

تتطلّب حزمة تطوير البرامج HTML5 لإعلانات الوسائط التفاعلية (IMA) توفّر AdDisplayContainer حتى إذا لم يكن هناك جزء عرض للإعلانات أو المحتوى. لهذا السبب، ننصحك بإخفاء AdDisplayContainer. في ما يلي مثال على كيفية إخفاء العنصر:

style.css

.ad-container {
  display: none;
}

عناصر التحكّم المخصّصة

بما أنّ AdDisplayContainer مخفي، يجب توفير عناصر تحكّم مخصّصة للتعامل مع التشغيل أثناء الفواصل الإعلانية. يتضمّن AdsManager طرقًا يمكن استخدامها لتنفيذ عناصر التحكّم المخصّصة هذه:

التعامل مع الإعلانات القابلة للتخطّي

بما أنّه لا يتوفّر AdDisplayContainer مرئي، لا يمكن لأداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية عرض زر تخطّي الإعلان. للتعامل مع الإعلانات القابلة للتخطّي، نفِّذ طرق IMA التالية:

يوضّح الرمز النموذجي التالي كيفية إجراء ذلك.

ads.js

يمكنك إعداد الدالة updateSkippable لتحديد ما إذا كان يمكن تخطّي الإعلان ومتى. يجب استدعاء هذه الدالة في كل 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();
});

في ما يلي التغييرات الرئيسية اللازمة لإعداد "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" مع الإعلانات الصوتية. للحصول على دعم بشأن مشاكل التنفيذ، يُرجى التواصل معنا من خلال مركز مساعدة "مدير إعلانات Google".