إعلانات صوتية

تدعم حزمة تطوير برامج HTML5 لإعلانات الوسائط التفاعلية الإعلانات الصوتية بإعدادات مشابهة لإعلانات الفيديو ولكن مع بعض الاختلافات الرئيسية. بالنسبة إلى أي جزء من إعداد إعلانات الوسائط التفاعلية غير الوارد في هذا الدليل، راجِع دليل البدء باستخدام HTML5.

استخدام علامة <audio> لتشغيل المحتوى

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

style.css

.ad-container {
  display: none;
}

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

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

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

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

ويوضح نموذج التعليمات البرمجية أدناه كيفية إجراء ذلك.

ads.js

يمكنك إعداد دالة updateSkippable لتحديد ما إذا كان يمكن تخطّي الإعلان ومتى يمكن تخطّيه. يجب استدعاء هذه الدالة عند كل حدث من أحداث إعلانات الوسائط التفاعلية (IMA) AD_PROGRESS. راجع دليل البدء للحصول على توجيهات حول كيفية إعداد أدوات الاستماع لأحداث إعلانات الوسائط التفاعلية.

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

وبخلاف إعلانات الفيديو، لا يمكن لإعلانات الوسائط التفاعلية توفير زر تخطي للإعلانات الصوتية. على المطوّرين إضافة واجهة مستخدم مخصّصة للإعلانات القابلة للتخطّي، ويمكن تنفيذ ذلك باستخدام علامة <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();
});

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