Audio ads

The IMA HTML5 SDK supports audio ads with a similar setup as video ads but with a few key differences. For any part of the IMA setup not covered in this guide, see the HTML5 Get started guide.

Use of an <audio> tag for content playback

The constructor for AdDisplayContainer takes a second argument named videoElement which IMA tracks as the content player. This argument accepts both a <video> or <audio> tag. For audio content and ads, this guide recommends using an <audio> tag to construct an AdDisplayContainer. If you have video content, you can use a <video> tag for showing a mix of audio and video ads:

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

Hiding the AdDisplayContainer

The IMA HTML5 SDK still requires an AdDisplayContainer even if there is no display portion to the ads or content. For this reason, we recommend hiding the AdDisplayContainer. Below is an example of how you can hide the element:

style.css

.ad-container {
  display: none;
}

Custom controls

Because the AdDisplayContainer is hidden, custom controls are needed to handle playback during ad breaks. AdsManager has methods that can be used to implement these custom controls:

Handling skippable ads

Because there is no visible AdDisplayContainer, the IMA SDK cannot show a Skip ad button. To handle skippable ads, implement the following IMA methods:

The sample code below demonstrates how to do this.

ads.js

You can set up an updateSkippable function to determine whether and when an ad can be skipped. This function should be called on each AD_PROGRESS IMA event. See the Getting started guide for directions on how to set up listeners for IMA events.

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

Unlike with video ads, IMA is not able to provide a skip button for audio ads. Developers must add custom UI for skippable ads, which can be done with a simple <button> tag. This updateSkipUI function updates the skip button based on if the ad is skippable, if the ad is currently skippable, and how much time is remaining until the ad becomes skippable. It makes use of the '.hidden' class, which is not provided by IMA. The .hidden class adds display: none; to the <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');
  }
}

Finally, set a listener for user clicks on your custom skip button. To skip ads, call the adsManager.skip() function.

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

These are the main changes needed to set up the IMA SDK with audio ads. For answers to implementation issues, visit the IMA SDK Technical Forum.