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

Companion Ads with the IMA Flash SDK Ad API

We recommend most publishers use Google Publisher Tag (GPT) for displaying companion ads intead of the SDK API. Check out our guide on Companion Ads with Google Publisher Tag.

Prerequisites

  • Flash video player with the IMA Flash SDK integrated. If you don't have one, check out our Get Started guide.
  • The Flash player must be embedded with allowscriptaccess="always".
  • A video tag URL that returns a VAST XML document with <CompanionAds> defined. [Sample tag]

Helpful Primers

  • IAB VAST spec - You can read about the <CompanionAds> element and its attributes and child nodes.

Display companion ads with the IMA SDK API

  1. Get a reference to an Ad object

    To display companion ads, get a reference to an Ad object through any of the AdEvent events dispatched from the AdsManager. We recommend using the AdEvent.STARTED event, as displaying companion ads should coincide with displaying the master video ad.

  2. Get and display companion ads

    Call Ad.getCompanionAds() to get an array of CompanionAd objects. Here you have the option of specifying CompanionAdSelectionSettings, which allows you to set filters on the companion ads for creative type, near fit percentage, resource type, and size criteria. For more information on these settings, see the Flash SDK API documentation.

    The CompanionAd objects returned by getCompanionAds can now be used to display the companion ads on the page using these guidelines:

    • For HTML ads, cast each Ad to an HtmlCompanionAd object and use the content property to get an HTML snippet. Place this snippet directly on the page with no modifications in a pre-defined <div> tag.
    • For Flash ads, cast each Ad to a FlashCompanionAd object. Next, add it to the display using the adsContainer property. Lastly, call the init() and start() methods to actually display the ad. Refer to the example below.

Sample code

Note: This sample code assumes that your page has been built using only Flash. For other types of pages, use CompanionAdEnvironments.HTML option instead.

...
import com.google.ads.ima.api.Ad;
import com.google.ads.ima.api.AdEvent;
import com.google.ads.ima.api.CompanionAdEnvironments;
import com.google.ads.ima.api.FlashCompanionAd;

import mx.containers.Canvas;
import mx.core.UIComponent;
...
  // Companion container placed somewhere on the Flash page.
  private var flashCompanionsContainer:Canvas;
  ...
  private function adStartedHandler(event:AdEvent):void {
    var ad:Ad = event.ad;
    if (ad != null) {
      var companions:Array = ad.getCompanionAds(CompanionAdEnvironments.FLASH, 300, 250);
      if (companions.length != 0) {
        var flashCompanion:FlashCompanionAd = FlashCompanionAd(companions[0]);
        var uiWrapper:UIComponent = new UIComponent();
        uiWrapper.addChild(flashCompanion.adsContainer);
        flashCompanionsContainer.addChild(uiWrapper);
        flashCompanion.init();
        flashCompanion.start();
      }
    }
  }
...

Send feedback about...

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