Get Started

The Google IMA SDK for HTML5 V3 allows developers to request and track VAST ads in a HTML5 video environment. For platform compatibility information and a detailed list of the video ad features supported by each of the IMA SDKs, see Support and Compatibility.

Download the code samples to assist with implementing the IMA HTML5 SDK.

If you'd rather follow along with a finished IMA SDK implementation, download the sample app or view it on GitHub. Alternatively, you can see a live version of this sample on GitHub Pages.

Prerequisites

Before you begin, you'll need the following:

  • Read through our compatibility page to make sure your intended use case is supported.
  • Three empty files:
    • index.html
    • style.css
    • ads.js
  • A server on which to host your files
    • If you have python, you can run python -m SimpleHTTPServer in the directory containing index.html and point your browser to localhost:8000

Laying out your HTML

To start off, you'll need a web page with a video player. Below is a sample layout (which also loads the SDK binary), the accompanying stylesheet, and an empty JavaScript file which we'll fill in as we go through the rest of the guide.

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

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="http://rmcdn.2mdn.net/Demo/vast_inspector/android.mp4"></source>
          <source src="http://rmcdn.2mdn.net/Demo/vast_inspector/android.webm"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script type="text/javascript" src="ads.js"></script>
  </body>
</html>
style.css
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

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

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

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
ads.js

Empty file; we'll fill this in as we go through the rest of the guide.

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:

ads.js
var videoContent = document.getElementById('contentElement');
videoContent.play();

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

Making your first ads request

Before moving on to the rest of the guide, remove the code you put in ads.js in the previous section. It should now be an empty file. All of the code snippets from here on out will be added to ads.js.

  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.

    ads.js
    var videoContent = document.getElementById('contentElement');
    var adDisplayContainer =
        new google.ima.AdDisplayContainer(
            document.getElementById('adContainer'),
            videoContent);
    // Must be done as the result of a user action on mobile
    adDisplayContainer.initialize();
  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 - that 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 DFP help center article. We'll then wire up the 'Play' button to call our requestAds function.

    ads.js
    // Re-use this AdsLoader instance for the entire lifecycle of your page.
    var adsLoader = new google.ima.AdsLoader(adDisplayContainer);
    
    // Add event listeners
    adsLoader.addEventListener(
        google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
        onAdsManagerLoaded,
        false);
    adsLoader.addEventListener(
        google.ima.AdErrorEvent.Type.AD_ERROR,
        onAdError,
        false);
    
    function onAdError(adErrorEvent) {
      // Handle the error logging and destroy the AdsManager
      console.log(adErrorEvent.getError());
      adsManager.destroy();
    }
    
    // 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 = 'https://pubads.g.doubleclick.net/gampad/ads?' +
        'sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&' +
        'impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&' +
        'cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=';
    
    // 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() {
      adsLoader.requestAds(adsRequest);
    }
  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.

    ads.js
    function onAdsManagerLoaded(adsManagerLoadedEvent) {
      // Get the ads manager.
      adsManager = adsManagerLoadedEvent.getAdsManager(
          videoContent);  // See API reference for contentPlayback
    
      // Add listeners to the required events.
      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);
    
      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.
      }
    }
    
    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);
      videoContent.pause();
    }
    
    function onContentResumeRequested() {
      // This function is where you should ensure that your UI is ready
      // to play content.
      videoContent.addEventListener('ended', contentEndedListener);
      videoContent.play();
    }

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

FAQ

I don't have python installed - can I just open the local copy of my html in a web browser?
No, this won't work. The IMA SDK is set up to load dependencies via the same protocol as the main page. When you open the file locally, it uses the file:// protocol. This protocol only works for resources stored locally on your machine, and since the IMA dependencies aren't stored locally on your machine, they will fail to load. If you can't use the recommended python method, try installing Apache server on your machine, though we strongly recommend the python solution for its simplicity.
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.

Send feedback about...

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