As of July 5, 2017 the Flash SDK is deprecated. We recommend using the HTML5 SDK for inline ads with web video content.

Flash Advanced Topics

Positioning ads

A few variables affect how ads are positioned within the AdsManager.adsContainer:

  1. adRenderingSettings.autoAlign, defaults to true.
  2. AdsManager.init(width, height) parameters.

When adRenderingSettings.autoAlign is true, the IMA Flash SDK positions all non-linear ads in the bottom center of the adsContainer, assuming the width and height parameters specified. It is up to the publisher to properly set the x and y parameters of the adsContainer so that it is in the bottom center of the player.

Alternatively, when adRenderingSettings.autoAlign is false, all ads are positioned in the top left (0,0) corner of the adsContainer. The publisher is still responsible for positioning the adsContainer, but this option allows for more flexibility with different positioning. For example, use this option if you prefer top centered non-linear ads.

Demonstrates how an ad is positioned within the ad slot based on the value of autoAlign.

Media selection

If multiple media files are available within a VAST response, properties within AdsRenderingSettings influence which file to select and play.

  • By default, linear video ads are selected before non-linear overlay ads during ad selection. To override this, set linearAdPreferred to false.
  • Bandwidth is defined per media file using the bitrate property, as part of the VAST standard. If your video player can detect or provide bandwidth information, providing this information can help the SDK deliver the best ad experience for your users.
  • By default, the IMA SDK will select either FLV or MP4 video media files and JPEG, GIF, PNG, or Flash non-linear media files. Use the mimeTypes property if you would prefer additional types. Refer to the API documentation for a list of valid audio and video MIME types.
  • The IMA SDK defaults to VideoDeliveryTypes.PROGRESSIVE delivered media files, but this can be changed by setting the delivery property to VideoDeliveryTypes.STREAMING.

private function adsManagerLoadedHandler(event:AdsManagerLoadedEvent):void {
  var adsRenderingSettings:AdsRenderingSettings = new AdsRenderingSettings();
  // Example call a publisher could make. Should return value in kbps.
  adsRenderingSettings.bitrate = detectBandwidth();
  // Prefer to play MP4s.
  adsRenderingSettings.mimeTypes = [VideoMimeTypes.MP4];
  adsManager = event.getAdsManager(contentPlayhead, adsRenderingSettings);
  // ... remaining code omitted.

Ad rules

IMA Flash SDK v3 supports fully automated ad playlists. This feature will insert ad breaks into the content as specified in Doubleclick for Publishers when trafficking your ads. It also greatly simplifies the video player code necessary to support ad breaks, including pre-rolls, mid-rolls and post-rolls.

  • When trafficking the ads in DFP, it is possible to specify various ad rules like "always play ad break at the beginning of the content" or "play a one minute ad break every 30 minutes of content".
  • When ads are requested, the ad server can return an ad playlist. The SDK processes the playlist and automatically schedules the ad breaks that have been specified.
  • When creating the AdsManager, a contentPlayhead object is passed in via the getAdsManager call. This object must have a time property that returns the current playhead position of the video. This object is used to track the progress of the content playback so ad breaks are automatically inserted at the times specified in DFP.
    // In order to support ad rules playlists, ads manager requires an object that
    // provides current playhead position for the content.
    var contentPlayhead:Object = {};
    contentPlayhead.time = function():Number {
      return contentPlayheadTime * 1000; // convert to milliseconds.
    // Get a reference to the AdsManager object through the event object.
    adsManager = event.getAdsManager(contentPlayhead, adsRenderingSettings);
  • The CONTENT_PAUSE_REQUESTED and CONTENT_RESUME_REQUESTED events are used to pause and resume the content when ad breaks are played.

Note: When the content has finished playing or the user has stopped playback, be sure to call AdsLoader.contentComplete in order to signal to the SDK that the content is done. The SDK will then play the post-roll ad break, if one has been scheduled. The ALL_ADS_COMPLETED event will be raised when ALL ad breaks have been played. In addition, note that content tracking begins when init() is called and you should always call init() before playing content.

Disabling Automatic Playback of Ad Breaks

In some circumstances you may want to prevent the SDK from playing ad breaks until you're ready for them. In this scenario, you can disable automatic playback of ad breaks in favor of letting the SDK know when you're ready for an ad break to play. With this configuaration, once the SDK has loaded an ad break, it will fire an AD_BREAK_READY event. When your player is ready for the ad break to start, you can call adsManager.start():

 * Initialize the AdsLoader and load the SDK
private function initAdsLoader():void {
  if (adsLoader == null) {
    // On the first request, create the AdsLoader.
    adsLoader = new AdsLoader();
    adsLoader.settings.autoPlayAdBreaks = false;
    // The SDK uses a 2 stage loading process. Without this call, the second
    // loading stage will take place when ads are requested. Including this
    // call will decrease latency in starting ad playback.

 * Invoked when the AdsLoader successfully fetched ads.
private function adsManagerLoadedHandler(event:AdsManagerLoadedEvent):void {
  // For non-auto ad breaks, listen for ad break ready

 * Invoked when the SDK has an ad break ready to play.
private function adBreakReadyHandler(event:AdEvent):void {
  // Once we're ready to play ads. To skip this ad break, simply return
  // from this handler without calling adsManager.start().

VAST event compatibility

This section lists the VAST events that are automatically reported to the server by the IMA Flash SDK v3 based on the information returned in the VAST response:

close, collapse, complete, creativeView, expand, firstQuartile, fullscreen, midpoint, mute, pause, resume, rewind, start, thirdQuartile and unmute

Reducing Latency - Best Practices

The key to reducing latency in your IMA-enabled web page is to do as much IMA-related set up as early as possible. You can do all of the following on your web page as early as you like before playing ads:

  • Create your AdsLoader and call AdsLoader.loadSdk().
  • Register your AdsLoader event listeners.
  • Create your AdsRequest.
  • Request ads.
  • Create your AdsRenderingSettings.
  • Create your content playhead.
  • Get your AdsManager instance.
  • Register your AdsManager event listeners.
  • Set the AdsManager handshake version.
Doing all of the above will initialize the IMA SDK and request and parse your ads response all before the user even clicks play on your video. When you're ready to play the ads, call AdsManager.init(...), add the ads container to your view, and call AdsManager.start. For more information on making your entire page more responsive, see the tips on evaluating network performance in the Chrome documentation.

Send feedback about...

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