Playing mobile video ads with the IMA HTML5 SDK

On iOS and Android, playback of video must be initialized with a user action, meaning a tap or click. Once the <video> element has been activated within a user action, it will remain usable for programmatic control later.

Prerequisites

  • HTML5 video player with the IMA HTML5 SDK integrated. If you don't have one, check out our Get Started guide.
  • A VAST ad tag URL that returns a mobile-friendly video creative.

Loading and playing ads on mobile web

The IMA HTML5 SDK uses the AdDisplayContainer to play the video ads. Internally, a <video> element is used. Both the content <video> element and AdDisplayContainer should be initialized within a user action. To initialize the content element, a call to the load() method is sufficient. To initialize the AdDisplayContainer, call the initialize() method in a user action.

Important: If the ads are loaded while the content <video> element is initializing, it is necessary to delay the video ad playback until the initialization has finished. Our research shows that this is when the loadedmetadata event is raised from the HTML5 video element. If this condition is not met, it can cause the content to not start correctly after the pre-roll ad has completed.

Simple approach to loading and playing ads

  1. User clicks to start playback.
  2. AdDisplayContainer is initialized.
  3. Content <video> element is initialized, waiting for the loadedmetadata event.
  4. Once the loadedmetadata event is received, ads are requested.

Optimized approach to loading and playing ads

  1. User clicks to start playback.
  2. Ads are requested.
  3. AdDisplayContainer is initialized.
  4. Content <video> element is initialized, waiting for the loadedmetadata event.
  5. Ads can only start once both the loadedmetadata event has been received and the ads have been loaded.
    • Once the loadedmetadata event is received, check whether ads have already been loaded. If they have, start them.
    • Once the ads are loaded, check whether the loadedmetadata event has already been received. If it has, start ads.

Sample optimized mobile video initialization code

var contentInitialized = false;
var adsLoaded = false;
var videoElement = document.getElementById('myContentVideo');

// Initial user action.
function startPlayback() {
  // Always initialize the container first.
  adDisplayContainer.initialize();

  // Initialize the content. This will start the playback once the ads
  // are loaded.
  initializeContent();
}

function initializeContent() {
  videoElement.src = 'http://mycdn.com/mycontent.mp4';
  videoElement.addEventListener(
      'loadedmetadata',
      function() {
        contentInitialized = true;
        if (adsLoaded) {
          startAds();
        }
      });
  // IMPORTANT: On older Android devices (2.3.5 or earlier), the loadedmetadata
  // event is not fired as a result of calling load() on the video element.
  // Instead, the event is received after calling play().
  videoElement.load();
}

function onAdsManagerLoaded() {
  // Get a handle to the adsManager as shown in the Get Started guide.
  ...
  adsLoaded = true;
  if (contentInitialized) {
    startAds();
  }
}

function startAds() {
  try {
    // Initialize the ads manager. Ad rules playlist will start at this time.
    adsManager.init(640, 360, google.ima.ViewMode.NORMAL);
    // Call start to show ads. Single video and overlay ads will
    // start at this time; this call will be ignored for ad rules, as ad rules
    // ads start when the adsManager is initialized.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
  }
}

Send feedback about...

IMA SDK for HTML5
Need help? Visit our support page.