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.


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

Starting 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.

Laying out your HTML

To start off, you'll need a web page with a video player. Below is a sample HTML layout (which also loads the SDK binary) and the accompanying CSS stylesheet.


    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" type="text/css" href="style.css">

    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src=""></source>
      <div id="adContainer"></div>
    <button id="playButton">Play</button>
    <script type="text/javascript" src="//"></script>
    <script type="text/javascript" src="ads.js"></script>


#mainContainer {
    position: relative;
    width: 640px;
    height: 360px;

  #adContainer {
    position: absolute;
    top: 0;
    left: 0;
    width: 640px;
    height: 360px;

  #contentElement {
    width: 640px;
    height: 360px;
    overflow: hidden;

  #playButton {
    height: 60px;
    padding: 15px;
    font-size: 22px;

Playing your video

At this point in your implementation, you should have a web page that displays a video player, but doesn't yet play that video. To get your video playing, open up ads.js and add the following lines:


var videoContent = document.getElementById('contentElement');
var playButton = document.getElementById('playButton');
playButton.addEventListener('click', function(){ });

Now when you view your page and click the play button, the video should start playing. In the rest of the guide, we'll add a pre-roll ad to this video.

Making your first ads request

  1. Create an ad display container

    In order for the SDK to display ads on your page, you need to tell it where to put them. In the html above, you defined a div with the id "adContainer". This div is set up to render on top of the video player. Using the code below, tell the SDK to render ads in that div. Also provide a handle to your content video player - the SDK will poll the current time of your player to properly place mid-rolls. After you create the ad display container, initialize it. On mobile devices, this initialization must be done as the result of a user action.


    var adDisplayContainer =
        new google.ima.AdDisplayContainer(
    // Must be done as the result of a user action on mobile
  2. Request ads

    Create an AdsLoader and define some event listeners. Then create an AdsRequest object to pass to this AdsLoader. The event listener for the ADS_MANAGER_LOADED event doesn't exist yet. It will be created later. We also use a sample test ad tag. To find out how to serve ads of your own, check out this Ad Manager help center article. We'll then wire up the 'Play' button to call our requestAds function.


    // Re-use this AdsLoader instance for the entire lifecycle of your page.
    var adsLoader = new google.ima.AdsLoader(adDisplayContainer);
    // Add event listeners
    function onAdError(adErrorEvent) {
      // Handle the error logging and destroy the AdsManager
    // An event listener to tell the SDK that our content video
    // is completed so the SDK can play any post-roll ads.
    var contentEndedListener = function() {adsLoader.contentComplete();};
    videoContent.onended = contentEndedListener;
    // Request video ads.
    var adsRequest = new google.ima.AdsRequest();
    adsRequest.adTagUrl = '' +
        'sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&' +
        'impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&' +
    // Specify the linear and nonlinear slot sizes. This helps the SDK to
    // select the correct creative if multiple are returned.
    adsRequest.linearAdSlotWidth = 640;
    adsRequest.linearAdSlotHeight = 400;
    adsRequest.nonLinearAdSlotWidth = 640;
    adsRequest.nonLinearAdSlotHeight = 150;
    var playButton = document.getElementById('playButton');
    playButton.addEventListener('click', requestAds);
    function requestAds() {
  3. Getting the AdsManager and Display Ads

    Once the ad display container is ready and ads have been retrieved, use the ads manager to display the ads.


    function onAdsManagerLoaded(adsManagerLoadedEvent) {
      // Get the ads manager.
      adsManager = adsManagerLoadedEvent.getAdsManager(
          videoContent);  // See API reference for contentPlayback
      // Add listeners to the required events.
      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.
      } catch (adError) {
        // An error may be thrown if there was a problem with the VAST response.
        // Play content here, because we won't be getting an ad.;
    function onContentPauseRequested() {
      // This function is where you should setup UI for showing ads (e.g.
      // display ad timer countdown, disable seeking, etc.)
      videoContent.removeEventListener('ended', contentEndedListener);
    function onContentResumeRequested() {
      // This function is where you should ensure that your UI is ready
      // to play content.
      videoContent.addEventListener('ended', contentEndedListener);;

That's it! You're now requesting and displaying your first ads. For more info on fine-tuning your implementation, check out Advanced Topics.


How can I debug implementation issues?
We have two SDK binaries: ima3.js and ima3_debug.js. If you're having issues implementing and you're not sure what's causing it, try loading ima3_debug.js to see a higher logging level.
Where are all the possible ad tag parameters described?
Create a master video tag manually.