Advertising with the IMA SDK, p. 1

Yesterday, we got everyone on board with video advertising, and the IMA SDK. Any questions with that — ask away! Today, I’m going to talk about pre-roll ads and how the IMA SDK handles them.

What is a pre-roll ad, I heard you asked? Pre-roll ads play before content — they are the first thing users see when they hit that “Play” button in the video player. Once a preroll finishes, IMA will send a signal telling the player it is time to start the non-ad content video.

Cool! Where do I see one in action?

To start off, navigate to our Video Suite Inspector. Once there, paste this ad tag into the input box, and hit the “Test Ad” button. You are now served our sample pre-roll ad tag.

To complete the picture, we host several other sample ad tags over here. They are great resources if you want something to validate your implementation. Keep in mind, though, that going into production you need live tags. The sample tags don’t generate any revenue!

Great. Going a bit more technical, what’s the 1–2–3 behind this?

Depending on the platform where the ad request originates, IMA will decide whether to use the same video player or create an additional one on-the-fly. But why?

Figure 1. “Standard” rendering visualization

Take, for instance, the HTML5 SDK. When you request an ad using the HTML5 SDK on desktop, IMA will layer an additional video player (SDK-owned) on top of your player that is already on the page (pictured above). This adds the benefit of allowing for the content video to buffer while the ad is being played. Once the ad finishes, IMA destroys its video player, cleans up the resources, and sends a signal to your video player to start the content. On the mobile web, the HTML5 SDK will use only one video player (i.e. the one you provide) since we are restricted to it.

For more details, visit IMA HTML5 Rendering.

So with these details in mind, and since the Video Suite Inspector runs on the HTML5 SDK, we are going to explore the HTML5 SDK in depth:

The moment you hit that “Test Ad” button, IMA will send out a request to the server specified in the ad tag. It could be DoubleClick, or AdSense, or even your own localhost where the tag resides. When the server receives the request, it will check under that account’s inventory to see if there is an ad matching the requirements specified in the VAST. If there isn’t, you get back an empty XML response. And when there is (woohoo!), you get a meaningful response that IMA will now parse.

Standard client-server interaction, isn’t it?

Figure 2. What a meaningful VAST response might look like

What if something went wrong and you need to be notified? Fear not, because IMA will throw an error at this stage, and resume to content on your behalf. This is crucial, since we don’t want users staring at a frozen video screen. Recall I shared the following SDK lifecycle diagram in my first post:

Figure 3. SDK’s lifecycle.

Here, the AdsLoader and AdsManager are literally the brains of the SDK. And there is a reason we separate the process into two stages: requesting + rendering. The AdsLoader is responsible for sending out the ad request and getting back an ad response. If an error occurs at this stage (network disconnectivity, for example), IMA throws an error with the AdsLoader. In other words, it is an ad load error. Any error that occurs prior to ad playback can be safely interpreted as an ad load error. The AdsManager is responsible for playing the ad. Well, not really. It dispatches events that tell the video player to play the ad. If an error occurs during ad playback, it is thrown against the AdsManager, and is otherwise known as an ad play error.

Once IMA parses the ad response, it constructs the ad interface, and renders the ad. The following events are dispatched for debugging purposes, which you can following along to get a sense of the lifecycle:

  • (5:03:51 PM) Ads loaded.
  • (5:03:51 PM) Ad event: loaded
  • (5:03:51 PM) Ad event: impression
  • (5:03:51 PM) Ad event: start
  • (5:03:54 PM) Ad event: firstquartile
  • (5:03:57 PM) Ad event: midpoint
  • (5:03:59 PM) Ad event: thirdquartile
  • (5:04:02 PM) Ad event: complete
  • (5:04:02 PM) Ad event: allAdsCompleted

Pretty self-explanatory, isn’t it?

In case you would like to learn more about what each of them means, check out the ima.AdEvent.Type reference for more details. I promise there will be a separate article going in depth about them.

Awesome! Do you have a checklist?


Do you have an ad tag? For our list of sample tags, see To generate your own:

Do you understand the SDK’s lifecycle? Refer to Figure 3 above for an elaborate and beautiful diagram.

Do you understand the ad’s lifecycle? Perfect.

- Vu, IMA SDK Team

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.