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

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

لا تزال أداة تطوير برامج HTML5 لإعلانات الوسائط التفاعلية تتطلّب 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/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 الفني.