Learn the SDK architecture

  • This guide outlines the lifecycle of the Interactive Media Ads (IMA) SDK and how it interacts with your video player and an ad server (Ad Manager, AdSense for Video, or Ad Exchange).

  • The process involves the IMA SDK requesting and parsing ad responses, delivering ads to the player, and managing playback and tracking events.

  • Ad selection is handled either through Ad Manager's Ad Unit filters or via auctions in AdSense or Ad Exchange.

  • Developers integrate the IMA SDK using script tags for HTML5 or dedicated apps for various platforms including Android, iOS, and tvOS.

  • The guide also highlights potential error conditions within the SDK lifecycle.
Select platform: HTML5 Android iOS tvOS

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 between your video player, the IMA SDK, and an ad server. The ad server can use Ad Manager, AdSense for Video (AFV), or Ad Exchange (AdX).

IMA basic interactions

  1. The web page or app loads the IMA SDK using:

    • an embedded script tag for HTML5
    • an app for Android, Google Cast, iOS, or tvOS

  2. The IMA SDK requests a VAST Response for the specific Ad Unit on the ad server. The ad server called, which can be either Ad Manager versus AFV or AdX, is determined by the ad tag URL.

  3. The ad server selects the best ad and sends a VAST response to the IMA SDK. Ads are selected using one of the following methods:

    • Ad Manager Ad Unit filters Line Item candidates
    • AdSense or Ad Exchange runs an auction

  4. The IMA SDK parses the VAST response, determines the correct media type based on environment, and delivers the inline video creative (and companion ads if needed) to the web page or app.

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

  6. The IMA SDK fires an impression ping and VAST tracking events, as needed.

Lifecycle

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.

HTML5 lifecycle image