Get started

IMA SDKs make it easy to integrate multimedia ads into your websites and apps. IMA SDKs can request ads from any VAST-compliant ad server and manage ad playback in your apps. With IMA client-side SDKs, you maintain control of content video playback, while the SDK handles ad playback. Ads play in a separate video player positioned on top of the app's content video player.

This guide demonstrates how to integrate the IMA SDK into a simple video player app. If you would like to view or follow along with a completed sample integration, download the simple example from GitHub. If you're interested in an HTML5 player with the SDK pre-integrated, check out the IMA SDK Plugin for Video.js.

IMA client-side overview

Implementing IMA client-side involves four main SDK components, which are demonstrated in this guide:

  • AdDisplayContainer: A container object where ads are rendered.
  • AdsLoader: An object that requests ads and handles events from ads request responses. You should only instantiate one ads loader, which can be reused throughout the life of the application.
  • AdsRequest: An object that defines an ads request. Ads requests specify the URL for the VAST ad tag, as well as additional parameters, such as ad dimensions.
  • AdsManager: An object that contains the response to the ads request, controls ad playback, and listens for ad events fired by the SDK.

Prerequisites

Before you begin, you'll need the following:

  • Three empty files:
    • index.html
    • style.css
    • ads.js
  • Python installed on your computer, or a web server to use for testing

1. Start a development server

Since the IMA SDK loads dependencies via the same protocol as the page from which it's loaded, you need to use a web server to test your app. The simplest way to start a local development server is to use Python's built-in server.

  1. Using a command line, from the directory that contains your index.html file run: 
      python -m http.server 8000
  2. In a web browser, go to http://localhost:8000/

You can also use any other web server, such as the Apache HTTP Server.

2. Create a simple video player

First, modify index.html to create a simple HTML5 video element, contained in a wrapping element, and a button to trigger playback. Also add the necessary tags to load the style.css and ads.js files. Then, modify styles.css to make the video player responsive for mobile devices. Finally, in ads.js, trigger video playback when the play button is clicked.

index.html 

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

After completing this step, when you open index.html in your browser (via your development server) you should be able to see the video element and the video should start when you click the play button.

3. Import the IMA SDK

Next, add the IMA framework using a script tag in index.html, before the tag for ads.js.

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Attach page and video player handlers

To modify the behavior of the video player with JavaScript, add event handlers that trigger the following actions:

  • When the page is finished loading, initialize the IMA SDK.
  • When the video play button is clicked, load ads (unless there are already ads loaded).
  • When the browser window is resized, update the video element and adsManager dimensions to make the page responsive for mobile devices
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. Create the ad container

In most browsers, the IMA SDK uses a dedicated ad container element for displaying both ads and ad-related UI elements. This container must be sized to overlay the video element from the top-left corner. The height and width of the ads placed in this container are set by the adsManager object, so you don't need to set these values manually.

To implement this ad container element, first create a new div within the video-container element. Then, update the CSS to position the element at the top-left corner of the video-element. Finally, define a variable for the container within the initializeIMA() function that runs when the page is loaded.

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. Initialize the AdsLoader and make an ads request

In order to request a set of ads, create an ima.AdsLoader instance. This instance takes an AdDisplayContainer object as an input and can be used to process ima.AdsRequest objects associated with a specified ad tag URL. The ad tag used in this example contains a 10-second pre-roll ad. You can test this, or any, ad tag URL using the IMA Video Suite Inspector.

As a best practice, only maintain one instance of ima.AdsLoader for the entire lifecycle of a page. To make additional ad requests, create a new ima.AdsRequest object, but re-use the same ima.AdsLoader. For more information, see the IMA SDK FAQ.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
      'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Listen for AdsLoader events

When ads are loaded successfully, the ima.AdsLoader emits an ADS_MANAGER_LOADED event. Parse the event passed to the callback to initialize the AdsManager object. The AdsManager loads the individual ads as defined by the response to the ad tag URL.

In addition, be sure to handle any errors that may occur during the loading process. If ads do not load, make sure that media playback continues, without ads, so as to not interfere with the user's experience.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Start the AdsManager

To start ad playback, you need to start the AdsManager. To fully support mobile browsers, this should be triggered by a user interaction.

ads.js 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Make the AdsManager responsive

To make sure that ads dynamically resize to match the size of the video player, if the screen changes size or orientation, the window resize event must call adsManager.resize().

ads.js 
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. Listen for AdsManager events

The AdsManager also fires several events that must be handled. These events are used to track state changes, trigger play and pause on the content video, and register errors.

Handling errors

The error handler created for the AdsLoader can serve as the error handler for the AdsManager by adding a new event handler with the same callback function.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

Triggering play and pause events

When the AdsManager is ready to insert an ad for display, it fires the CONTENT_PAUSE_REQUESTED event. Handle this event by triggering a pause on the underlying video player. Similarly, when an ad completes, the AdsManager fires the CONTENT_RESUME_REQUESTED event. Handle this event by restarting playback on the underlying content video.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

Triggering click-to-pause on mobile devices

Since the AdContainer overlays the video element, users cannot interact directly with the underlying player. This can confuse users on mobile devices, who expect to be able to tap a video player to pause playback. To address this issue, the IMA SDK passes any clicks that are not handled by IMA from the ad overlay to the AdContainer element, where they can be handled. This does not apply to linear ads on non-mobile browsers, as clicking the ad opens the clickthrough link.

To implement click-to-pause, add a click handler to the AdContainer and trigger play or pause events on the underlying video.

ads.js 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Triggering play on non-linear ads

The AdsManager pauses the content video when an ad is ready to play, but this behavior doesn't account for non-linear ads, where the content should continue to play while the ad is displayed. To support non-linear ads, listen for the AdsManager to emit the LOADED event. Then, check if the ad is linear, and if not, resume playback on the video element.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

That's it! You're now requesting and displaying ads with the IMA SDK. To learn about more advanced SDK features, see the other guides or the samples on GitHub.