SDK Architecture

This guide provides an overview of the SDK lifecycle and the interactions between your video player, the IMA SDK, and an ad server.

Basic interactions

The following diagram illustrates and annotates the interactions among your video player, the IMA SDK v3, and an ad server. The ad server may be using Ad Manager, AdSense for Video (AFV), or Ad Exchange (AdX). The diagram helps you visualize how things will work when you finish implementing your integration with the SDK.

  1. A Line Item targets an Ad Unit in Ad Manager.

  2. The web page loads the IMA SDK via

    • an embedded script tag for HTML5
    • along with the app for iOS and Android
  3. IMA SDK requests a VAST Response for the specific Ad Unit from Ad Manager or AFV/AdX depending on the ad tag.

  4. The ad server selects the best ad:

    • Ad Manager Ad Unit filters Line Item candidates
    • AdSense/Ad Exchange runs an auction
  5. The ad server sends a VAST response with its URL to IMA SDK.

  6. The IMA SDK parses the VAST response and determines the correct media type based on environment.

  7. The IMA SDK retrieves the in-line video creative (and companion ads if needed).

  8. The video player negotiates the details with the IMA SDK and plays the ads.

  9. The IMA SDK fires an impression ping (and VAST tracking events as needed).

Interactions between SDK and video player

The following diagram illustrates and annotates the interactions between the IMA SDK v3 and your video player. It is meant to help you visualize how things will work when done implementing your integration. The diagram applies to HTML5 integrations.

  1. Web page loads the IMA SDK.
  2. Web page loads the GPT Library (only for companions).
  3. Web page registers companion ad slots with GPT library.
  4. Video Player creates an instance of AdDisplayContainer [HTML5 only] and then calls AdDisplayContainer.initialize in response to the first user interaction with the web page.
  5. Video Player creates an instance of AdsLoader (generally after the user has clicked play or upon autoplay) and passes in the AdDisplayContainer object.
  6. Video Player registers listeners for the ADS_MANAGER_LOADED and AD_ERROR events with the AdsLoader instance.
  7. Video Player creates AdsRequest instance and populates it with the ad tag and the dimensions for linear and non-linear ads.
  8. Video Player calls AdsLoader.requestAds instance and passes it the AdsRequest object just created.
  9. IMA SDK requests and receives the VAST response.
  10. IMA SDK fires the ADS_MANAGER_LOADED event.
  11. Video Player calls getAdsManager. May optionally pass AdsRenderingSettings object and content tracker objects for ad rules.
  1. Video Player registers listeners for AD_ERROR, CONTENT_PAUSE_REQUESTED, CONTENT_RESUME_REQUESTED, and ALL_ADS_COMPLETED with the instance of AdsManager. Listeners for other events may also be added.
  2. Video Player calls AdsManager.init and passes it the height and width of the master video and the desired View Mode.
  3. Video Player calls AdsManager.start.
  5. Video Player pauses content.
  6. AdsManager instance on player plays the ads. AdsManager plays video in AdDisplayContainer for HTML5. IMA SDK fires impression ping and info events like START, IMPRESSION, and quartile events while ads are playing.
  8. Video Player resumes content.
  9. IMA SDK fires ALL_ADS_COMPLETE event.


This diagram shows the full lifecycle of the IMA SDK. Constructor and method calls are highlighted in blue, events are highlighted in red, and error conditions are shown with red connectors and red text. Use this as a reference as you work through your IMA implementation.

Send feedback about...

Need help? Visit our support page.