Annunci audio

L'SDK IMA per HTML5 supporta gli annunci audio con una configurazione simile a quella degli annunci video, ma con alcune importanti differenze. Per qualsiasi parte della configurazione IMA non trattata in questa guida, consulta la Guida introduttiva a HTML5.

L'utilizzo di un tag <audio> per la riproduzione dei contenuti

Il costruttore di AdDisplayContainer utilizza un secondo argomento denominato videoElement, che IMA monitora come player di contenuti. Questo argomento accetta sia un tag <video> che un tag <audio>. Per i contenuti audio e gli annunci, questa guida consiglia di utilizzare un tag <audio> per creare una AdDisplayContainer. Se disponi di contenuti video, puoi utilizzare un tag <video> per mostrare un mix di annunci audio e 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);

Occultamento dell'AdDisplayContainer

L'SDK IMA per HTML5 richiede comunque un elemento AdDisplayContainer anche se non è presente alcuna parte di visualizzazione degli annunci o dei contenuti. Per questo motivo, consigliamo di nascondere AdDisplayContainer. Di seguito è riportato un esempio di come nascondere l'elemento:

style.css

.ad-container {
  display: none;
}

Controlli personalizzati

Poiché AdDisplayContainer è nascosto, sono necessari controlli personalizzati per gestire la riproduzione durante le interruzioni pubblicitarie. AdsManager offre metodi che possono essere utilizzati per implementare questi controlli personalizzati:

Gestione degli annunci ignorabili

Poiché non è visibile alcun elemento AdDisplayContainer, l'SDK IMA non può mostrare un pulsante Salta annuncio. Per gestire gli annunci ignorabili, implementa i seguenti metodi IMA:

Il codice campione riportato di seguito mostra come eseguire questa operazione.

ads.js

Puoi impostare una funzione updateSkippable per determinare se e quando è possibile saltare un annuncio. Questa funzione deve essere richiamata a ogni evento IMA AD_PROGRESS. Consulta la Guida introduttiva per istruzioni su come impostare i listener per gli eventi 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);
  }

A differenza degli annunci video, IMA non è in grado di fornire un pulsante Salta per gli annunci audio. Gli sviluppatori devono aggiungere un'interfaccia utente personalizzata per gli annunci ignorabili. Questa operazione può essere eseguita con un semplice tag <button>. Questa funzione updateSkipUI aggiorna il pulsante Salta in base al fatto che l'annuncio sia ignorabile, che al momento sia ignorabile e al tempo rimanente prima che l'annuncio diventi ignorabile. Utilizza la classe '.hidden', che non è fornita da IMA. Il corso .hidden aggiunge display: none; alla classe <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');
  }
}

Infine, imposta un listener per i clic degli utenti sul pulsante Salta personalizzato. Per saltare gli annunci, chiama la funzione adsManager.skip().

skipButton.addEventListener('click', () => {
  adsManager.skip();
});

Queste sono le principali modifiche necessarie per configurare l'SDK IMA con annunci audio. Per risposte ai problemi di implementazione, visita il forum tecnico dell'SDK IMA.