Get Started

On June 1, 2017, Google will cease supporting the IMA SDK for Flash and Flash VPAID ads in the HTML5 SDK. We strongly encourage all publishers using the Flash SDK to migrate to the HTML5 SDK. We also strongly encourage advertisers trafficking Flash VPAID ads to migrate those ads to JavaScript VPAID.

This guide covers the following:

Configuring your Flash/Flex environment

Your first ads request

To request ads from DoubleClick, AdSense, or any VAST-compliant ad server:

  1. Create an Instance of AdsLoader to Load your Ads
  2. Add Event Listeners
  3. Create an AdsRequest object
  4. Request Ads from the Ad Server

  1. Create an Instance of AdsLoader to Load your Ads
    Import the relevant packages (shown below) and create an AdsLoader instance. To improve latency, create your AdsLoader instance when you first create your player. In our example, we call this initAdsLoader method at the end of our player's constructor.
    private var adsLoader:AdsLoader;
    
    /**
     * Initialize the AdsLoader and load the SDK
     */
    private function initAdsLoader():void {
      if (adsLoader == null) {
        // On the first request, create the AdsLoader.
        adsLoader = new AdsLoader();
        // 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.
        adsLoader.loadSdk();
      }
    }

    Note: If you use DFP and wish to enable stream-level frequency caps, be sure that multiple requests from a single stream use the same AdsLoader object.

  2. Add Event Listeners
    Add an event listener for the ADS_MANAGER_LOADED and AD_ERROR events on the AdsLoader.
    private function initAdsLoader():void {
      if (adsLoader == null) {
        // On the first request, create the AdsLoader.
        adsLoader = new AdsLoader();
        // 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.
        adsLoader.loadSdk();
        adsLoader.addEventListener(AdsManagerLoadedEvent.ADS_MANAGER_LOADED,
                                   adsManagerLoadedHandler);
        adsLoader.addEventListener(AdErrorEvent.AD_ERROR, adsLoadErrorHandler);
      }
    }
  3. Create an AdsRequest object
    Create an AdsRequest object for each tag you are using, and set the size parameters on it. The size parameters are used during ad selection after the response has been received.
    private function requestAds(adTag:String):void {
      // The AdsRequest encapsulates all the properties required to request ads.
      var adsRequest:AdsRequest = new AdsRequest();
      adsRequest.adTagUrl = adTag;
      adsRequest.linearAdSlotWidth = videoPlayer.width;
      adsRequest.linearAdSlotHeight = videoPlayer.height;
      adsRequest.nonLinearAdSlotWidth = videoPlayer.width;
      adsRequest.nonLinearAdSlotHeight = videoPlayer.height;
    }
  4. Request Ads from the Ad Server
    Call the requestAds method on AdsLoader to request an ad.
     private function requestAds(adTag:String):void {
      // The AdsRequest encapsulates all the properties required to request ads.
      var adsRequest:AdsRequest = new AdsRequest();
      adsRequest.adTagUrl = adTag;
      adsRequest.linearAdSlotWidth = videoPlayer.width;
      adsRequest.linearAdSlotHeight = videoPlayer.height;
      adsRequest.nonLinearAdSlotWidth = videoPlayer.width;
      adsRequest.nonLinearAdSlotHeight = videoPlayer.height;
      // Instruct the AdsLoader to request ads using the AdsRequest object.
      adsLoader.requestAds(adsRequest);
    }

Back to top

Displaying ads

After requesting ads from the DoubleClick network, AdSense network, or any VAST-compliant ad servers, use the AdsManager to display them.

Complete the following steps to display your ads.

  1. Get the Ads Manager
  2. Add Event Listeners
  3. Initialize and Play the Ads
  4. Content Complete
  5. Destroy the Ads Manager
  1. Get the Ads Manager

    Once the ad is loaded successfully, the callback method that you added (in the Add Event Listeners step of the Requesting Ads section) for the ADS_MANAGER_LOADED event is called. Get the AdsManager instance from the AdsManagerLoadedEvent by calling getAdsManager. The parameters are optional and are discussed below this code snippet.

    /**
     * Invoked when the AdsLoader successfully fetched ads.
     */
    private function adsManagerLoadedHandler(event:AdsManagerLoadedEvent):void {
      // Publishers can modify the default preferences through this object.
      var adsRenderingSettings:AdsRenderingSettings =
          new AdsRenderingSettings();
    
      // 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 following optional parameters could be important, depending on your particular use case:

    • contentPlayhead:Object - Allows the SDK to track the playback of the content when the response from the ad server is a playlist or ad rules response. This object is required for the SDK to properly display ad rules responses.
    • adsRenderingSettings:AdsRenderingSettings - These settings further allow you to specify which ads are chosen if multiple media files are present in the VAST response.

    For further details about these parameters, see the API Reference.

  2. Add Event Listeners

    Four event listeners must be registered before an AdsManager will play any ads:

    • AdEvent.CONTENT_PAUSE_REQUESTED
    • AdEvent.CONTENT_RESUME_REQUESTED
    • AdEvent.ALL_ADS_COMPLETED
    • AdErrorEvent.AD_ERROR

    Register handlers for each of these events (and others if needed).

    /**
     * Invoked when the AdsLoader successfully fetched ads.
     */
    private function adsManagerLoadedHandler(event:AdsManagerLoadedEvent):void {
      // Publishers can modify the default preferences through this object.
      var adsRenderingSettings:AdsRenderingSettings =
          new AdsRenderingSettings();
    
      // In order to support ad rules, 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);
      if (adsManager) {
        // Add required ads manager listeners.
        // ALL_ADS_COMPLETED event will fire once all the ads have played. There
        // might be more than one ad played in the case of ad pods and ad rules.
        adsManager.addEventListener(AdEvent.ALL_ADS_COMPLETED,
                                    allAdsCompletedHandler);
        // If ad is linear, it will fire content pause request event.
        adsManager.addEventListener(AdEvent.CONTENT_PAUSE_REQUESTED,
                                    contentPauseRequestedHandler);
        // When ad finishes, content resume event will be fired.
        // For example, if ad rules response only has post-roll, content
        // resume will be fired for pre-roll ad (which is not present) to signal
        // that content should be started or resumed.
        adsManager.addEventListener(AdEvent.CONTENT_RESUME_REQUESTED,
                                    contentResumeRequestedHandler);
        // All AD_ERRORs indicate fatal failures. You can discard the AdsManager and
        // resume your content in this handler.
        adsManager.addEventListener(AdErrorEvent.AD_ERROR,
                                    adsManagerPlayErrorHandler);
      }
    }
  3. Initialize and Play the Ads

    Call adsManager.init(...) before starting the content, even if the ad is to be played in the middle or at the end of your content. This allows flexibility for future compatibility. For example, if an ad rules response is returned from the ad server, you won't have to change the player code. When you are ready to play the ad, attach the adsManager.adsContainer to your player and invoke adsManager.start().

    /**
     * Invoked when the AdsLoader successfully fetched ads.
     */
    private function adsManagerLoadedHandler(event:AdsManagerLoadedEvent):void {
      // Publishers can modify the default preferences through this object.
      var adsRenderingSettings:AdsRenderingSettings =
          new AdsRenderingSettings();
    
      // In order to support ad rules ads, 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);
      if (adsManager) {
        // Add required ads manager listeners.
        // ALL_ADS_COMPLETED event will fire once all the ads have played. There
        // might be more than one ad played in the case of ad pods and ad rules.
        adsManager.addEventListener(AdEvent.ALL_ADS_COMPLETED,
                                    allAdsCompletedHandler);
        // If ad is linear, it will fire content pause request event.
        adsManager.addEventListener(AdEvent.CONTENT_PAUSE_REQUESTED,
                                    contentPauseRequestedHandler);
        // When ad finishes or if ad is non-linear, content resume event will be
        // fired. For example, if ad rules response only has post-roll, content
        // resume will be fired for pre-roll ad (which is not present) to signal
        // that content should be started or resumed.
        adsManager.addEventListener(AdEvent.CONTENT_RESUME_REQUESTED,
                                    contentResumeRequestedHandler);
        adsManager.addEventListener(AdErrorEvent.AD_ERROR,
                                    adsManagerPlayErrorHandler);
    
        // If your video player supports a specific version of VPAID ads, pass
        // in the version. If your video player does not support VPAID ads yet,
        // just pass in 1.0.
        adsManager.handshakeVersion("1.0");
        // Init should be called before playing the content in order for ad rules
        // ads to function correctly.
        adsManager.init(videoPlayer.videoDisplay.width,
                        videoPlayer.videoDisplay.height,
                        ViewModes.NORMAL);
    
        // Add the adsContainer to the display list. Below is an example of how
        // to do it with our Flex player.
        var flexAdContainer:SpriteVisualElement = new SpriteVisualElement();
        flexAdContainer.addChild(adsManager.adsContainer);
        (videoPlayer.videoDisplay.parent as Group).addElement(flexAdContainer);
    
        // Start the ad playback.
        adsManager.start();
      }
    }
  4. Content Complete

    When your content has finished, call adsLoader.contentComplete(). If there are any post-roll ads, they will be played now.

     /**
      * Invoked when the video content has finished.
      */
     private function onContentComplete():void {
       adsLoader.contentComplete();
     }
  5. Destroy the Ads Manager
    When the AdsManager dispatches these two events:
    • AdEvent.ALL_ADS_COMPLETED
    • AdEvent.AD_ERROR

    remove all attached listeners and call destroy().

That's it! You're now requesting and displaying your first ads. For more info on fine-tuning your implementation, check out advanced topics.

Back to top

Sample Code

Expand the branches below to view the samples. The sample code is also available for download.

Note: Although these examples utilize Adobe Flex 4.0, it is not required for the SDK to function properly.

Back to top

Send feedback about...

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