Google Interactive Media Ads

Working with Ads (Deprecated)

DoubleClick for Publishers (DFP) and AdSense for video and games enable publishers to earn revenue from their rich media content through interactive media ads. While DFP enables publishers to create and traffic ads, publishers cannot create AdSense ads as they are indirectly sold and delivered by the AdSense network. Additionally, code samples with demos are available for download.

This section explains how publishers can request and display ads using the IMA SDK, and provides information on supported ad types.

Request Ads

The following steps enable you to request ads from DoubleClick, AdSense, and any VAST-compliant ad servers. You do not need to load the SDK as the AdsLoader class does that internally.

  1. Create an instance of AdsLoader to Load your Ads
  2. Add Event Listeners
  3. Create Objects for Ad Requests
  4. Request Ads from the Various Networks


  1. Create an instance of AdsLoader to Load your Ads
    Import the relevant packages, create an AdsLoader instance, and add it to the stage.
     import com.google.ads.instream.api.AdsRequest;
     import com.google.ads.instream.api.AdsRequestType;
     import com.google.ads.instream.api.AdsLoader;
     import com.google.ads.instream.api.AdsLoadedEvent;
     import com.google.ads.instream.api.AdErrorEvent;
     import com.google.ads.instream.api.AdsManager;
    
     // Create AdsLoader
     var adsLoader:AdsLoader = new AdsLoader();
     stage.addChild(adsLoader);
     
  2. Add Event Listeners
    Add an event listener for the ADS_LOADED event on AdsLoader. We also recommend adding an event listener for the AD_ERROR event.
     //Add an event listener
     adsLoader.addEventListener(AdsLoadedEvent.ADS_LOADED, onAdsLoaded);
     adsLoader.addEventListener(AdErrorEvent.AD_ERROR, onAdError);
     
  3. Create Objects for Ad Requests
    Create an AdsRequest object for each type of ad (DFP, Dynamic Allocation, AFV, or AFG) that you are using, and set the appropriate parameters on it. Note that the publisher_id parameter is not required for Dynamic Allocation request as it is provided during the network configuration process in DFP.
     // Create DFP AdsRequest (no Dynamic Allocation)
     var adsRequestDFP:AdsRequest = new AdsRequest();
     adsRequestDFP.adSlotWidth = 300;
     adsRequestDFP.adSlotHeight = 250;
     adsRequestDFP.adTagUrl = "http://ad.doubleclick.net/pfadx/AngelaSite;foo=prodtest;sz=728x90;dcmt=text/html";
     adsRequestDFP.adType = AdsRequestType.VIDEO;
    
     // Create DFP AdsRequest with Dynamic Allocation
     var adsRequestDA:AdsRequest = new AdsRequest();
     adsRequestDA.adSlotWidth = 300;
     adsRequestDA.adSlotHeight = 250;
     adsRequestDA.adTagUrl = "http://ad.doubleclick.net/pfadx/AngelaSite;foo=prodtest;sz=728x90;dcmt=text/html";
     adsRequestDA.adType = AdsRequestType.TEXT_OVERLAY;
     adsRequestDA.channels = ["angela"];
     adsRequestDA.contentId = "123";
    
     // Create AFV (AdSense for Video) AdsRequest
     var adsRequestAFV:AdsRequest = new AdsRequest();
     adsRequestAFV.adSlotWidth = 400;
     adsRequestAFV.adSlotHeight = 250;
     adsRequestAFV.publisherId= "ca-video-googletest1";
     adsRequestAFV.adType = AdsRequestType.TEXT_OVERLAY;
     adsRequestAFV.channels = ["angela"];
     adsRequestAFV.contentId = "123";
    
     // Create AFG (AdSense for Games) AdsRequest
     var adsRequestAFG:AdsRequest = new AdsRequest();
     adsRequestAFG.adSlotWidth = 468;
     adsRequestAFG.adSlotHeight = 60;
     adsRequestAFG.publisherId= "ca-games-test";
     adsRequestAFG.adType = AdsRequestType.GRAPHICAL_OVERLAY;
     adsRequestAFG.channels = ["poker"];
     adsRequestAFG.contentId = "1";
     
  4. Request Ads from the Various Networks
    Call the requestAds method on AdsLoader to request an ad.
     // Request DFP Ad
     adsLoader.requestAds(adsRequestDFP);
     // Request Dynamic Allocation Ad (uncomment below line to use)
     //adsLoader.requestAds(adsRequestDA);
     // Request AFV Ad (uncomment below line to use)
     //adsLoader.requestAds(adsRequestAFV);
     // Request AFG Ad (uncomment below line to use)
     //adsLoader.requestAds(adsRequestAFG);
    
     

Using AdsRequest parameters

AdsRequest contains parameters for DoubleClick as well as AFV. Since the two systems are very different – DoubleClick is reservation based whereas AFV is auction based – the AdsRequest object lets you specify both an ad tag (pointing to a specific reserved ad) as well as parameters to configure the auction (like what types of ads should participate in the auction, etc.).

Below are some notes on using AdsRequest:

  • adSlotWidth and adSlotHeight must be set to indicate the width and height of the slot within which the ad must fit. The SDK uses this where possible to request ads of the correct sizes.
  • adSlotHorizontalAlignment and adSlotVerticalAlignment are optional parameters that provide information about how the ad slot is aligned within its larger display area. The SDK uses this where possible to request ads that work best visually within the slot.
  • adTagUrl can be set if you are requesting dynamically allocated ads or DoubleClick-only ads. Usually, you should have an ad tag URL provided by a trafficker familiar with DFP or DFA (otherwise see the next bullet). If you are using the SDK to request AFV-only ads, this is not required.
  • contentId must be set if you are requesting dynamically allocated ads or AFV-only ads. This parameter identifies the video content within which the ads will be displayed.
  • publisherId must be set if you are requesting AFV-only ads.
  • adType indicates which types of AFV ads should participate in the auction for ads. Video is the default.
  • Additional parameters such as maxTotalAdDuration, channels, etc. are available to configure which ads participate in the auction.

Refer to the API reference for details on valid values.

Back to top

Display Ads

After requesting ads from either the DoubleClick, AdSense network, or any VAST compliant ad servers, you can display the ads by using the Ads Manager. Three different types of ads managers—Video, Flash, and Custom Content— can be used depending on your ads.

The following steps enable you to display your ads, and are illustrated in the sample code below.

  1. Get the Ads Manager
  2. Check for Ad Types
  3. Unload the Ads Manager

  1. Get the Ads Manager

    Once the ad is loaded successfully, the callback method that you added for the ADS_LOADED event is called. Get the AdsManager instance from the AdsLoadedEvent instance passed in. Use the AdsManager object for displaying the ads and add event listeners to listen and respond to content activities.

    The AdsManager represents ads of a particular type – either video, Flash, or customContent ads. These ad types must be displayed in slightly different ways, as explained below.

    Note: There are no separate ads managers for DoubleClick and AdSense ads. VideoAdsManager supports all video ads. FlashAdsManager supports all Flash ads.


  2. Check for Ad Types

    The main differences in displaying video, Flash, and custom content ads are explained as follows:

    Video Ads Manager
    • Set clickTrackingElement to a visual element on which to track clicks for the video ad. The SDK does not automatically use the video player area for click tracking because the player skin may include controls (buttons for play, pause, stop, etc.), and these button clicks are not the same as ad clicks.
    • Call load before play to allow prebuffer of necessary assets.
    • Call play and pass in the playback object in which to play the video ad. The playback object is usually FLVPlayback or Video.

    Flash Ads Manager
    • Set the x and y coordinates to indicate the position on the stage where the ad should be displayed.
    • Call load before calling play to allow prebuffer of necessary assets.
    • Call play(container) to display the Flash ad. The container is a DisplayObjectContainer that will be used to display the ad.

    Custom Content Ads Manager

    Custom content ads are ads in a format that the SDK does not recognize, i.e., they are neither DoubleClick- nor AdSense-formatted ad responses. We allow the user to access the content in these ads to allow publishers to use the SDK to process ads from other systems if they wish.

    Note: load and play are not supported on custom content ads. Since the SDK does not recognize these ads, it cannot display anything.


  3. Unload the Ads Manager

    When the ad display is completed, you can remove listeners that are attached to the Ads Manager and unload the Ads Manager.

Sample Code

 import com.google.ads.instream.api.AdsRequest;
 import com.google.ads.instream.api.AdsLoader;
 import com.google.ads.instream.api.AdsLoadedEvent;
 import com.google.ads.instream.api.AdErrorEvent;
 import com.google.ads.instream.api.AdsManager;
 import com.google.ads.instream.api.AdsManagerTypes;

 private function onAdsLoaded(adsLoadedEvent:AdsLoadedEvent):void {
  // Get AdsManager
  var adsManager:AdsManager = adsLoadedEvent.adsManager;
  adsManager.addEventListener(AdErrorEvent.AD_ERROR, onAdError);

  // Listen and response to events which require you to pause/resume content
  adsManager.addEventListener(AdEvent.CONTENT_PAUSE_REQUESTED, onPauseRequested);
  adsManager.addEventListener(AdEvent.CONTENT_RESUME_REQUESTED, onResumeRequested);

  // Check if the ads loaded are video or flash ads
  if (adsManager.type == AdsManagerTypes.VIDEO) {
    var videoAdsManager:VideoAdsManager = adsManager as VideoAdsManager;
    // Add a video specific complete event
    adsManager.addEventListener(AdEvent.COMPLETE, onVideoAdComplete);
    // Set a visual element on which clicks should be tracked for video ads
    videoAdsManager.clickTrackingElement = clickMovieClip;
    // Call load followed by play
    // FLVPlayback or Video object indicates where to display the ad
    // If you are requesting an overlay without animation (uncomment below line to use):
    // adsManager.decorated = false;
    adsManager.load(videoOnStage);
    adsManager.play(videoOnStage);
  } else if (adsManager.type == AdsManagerTypes.FLASH) {
    var flashAdsManager:FlashAdsManager = adsManager as FlashAdsManager;
    // Set x, y coordinates to indicate where to display the Flash ad on the stage
    flashAdsManager.x = 10;
    flashAdsManager.y = 10;
    // Call load followed by play
    flashAdsManager.load();
    // Pass in a visual element that will house the non-linear ad. For example,
    // this can be the video player itself, if the video player is an
    // instance of DisplayObjectContainer.
    flashAdsManager.play(visualContainer);
  }
 }

 private function onVideoAdComplete(event:AdEvent):void {
   if (adsManager) {
     //Remove listeners that were attached to adsManager
     removeListeners();
     adsManager.unload();
     adsManager = null;
   }
 }
 

Listening for Events

  • Listen for the AD_ERROR event on AdsManager to handle any errors that are raised.
  • Listen for the CONTENT_PAUSE_REQUIRED and CONTENT_RESUME_REQUIRED events. These events are raised by the AdsManager for certain ads that work best if the video content is paused while they are displayed.
    • For example, video ads and the publisher’s video content are played in the same video player; it is best if content is paused before the ad starts.
    • Another example is a full-screen Flash-in-Flash ad that is designed to be overlaid on top of the whole video player visual area; it is best if content is paused before the ad is displayed since it would otherwise hide the content. Instead of asking publishers to hook different events for different types of ads, we raise these common events to simplify publisher code.
  • You can listen for additional events, though it is not required.
    • Events supported for video ads are CLICK, LOADED, STARTED, COMPLETE, STOPPED, PAUSED, MIDPOINT, FIRST_QUARTILE, THIRD_QUARTILE, RESTARTED, VOLUME_MUTED.
    • Events supported for Flash ads are CLICK, LOADED, STARTED, SIZE_CHANGED, CUSTOM_EVENT.

Back to top

Video Ad Bandwidth Selection

Bandwidth is defined per media file using the bitrate element, as part of the VAST standard. If your video players can detect or provide bandwidth information, you can set the bandwidth accordingly to determine which bitrates are suitable for your users. The bitrate information is in the ad response which is used by the IMA SDK during media selection to map to the appropriate bandwidth, which is categorized into three groups: LOW, MEDIUM, and HIGH. Otherwise, you can omit bandwidth selection and let the SDK perform auto-detection of bandwidth for ads served from the DoubleClick network. View the API reference for details on bandwidth constants.

Bitrate to bandwidth mapping is listed as follows:

Bandwidth Range Bitrate (Kbps)
LOW 0 - 139
MEDIUM 140 - 249
HIGH > 249

You can specifiy the bandwidth via the following methods:

Manual bandwidth mapping

To specify the bandwidth mapping, you must set the bandwidth value to either LOW, MEDIUM, or HIGH. Bandwidth constants can be viewed here. The sample code below shows how to set the bandwidth mapping of your videos.

Sample Code

 var videoAdsManager:VideoAdsManager = adsManager as VideoAdsManager;
 var mediaSelectionSettings:MediaSelectionSettings =
              videoAdsManager.mediaSelectionSettings;
 // Setting bandwidth to HIGH will map to the bitrate as specified above.
 // Similarly, LOW and MEDIUM bandwidths can be set.
 mediaSelectionSettings.bandwidth = VideoAdBandwidth.HIGH;
 videoAdsManager.mediaSelectionSettings = mediaSelectionSettings;

Auto-bandwidth detection

In auto-bandwidth detection, the DoubleClick ad server determines users' bandwidth from their ISP-provided IP address. The bandwidth information is included in the ad response which is then used by the SDK during media selection. Therefore, you do not have to set any bandwidth constants to mediaSelectionSettings.bandwidth. View the API reference for MediaSelectionSettings properties.

Back to top

AdTypes Support

IMA supports several ad types—audio, video, text, and graphical. While audio and video ad types are not dependent on size specifications, text and graphical ad types must be accompanied by the correct sizes (adSlotWidth and adSlotHeight specifications) to be displayed on your media content. Otherwise, ads might not display properly.

Text and graphical ad types can be rendered as either overlays or full slots. Overlays are displayed at the bottom third of the video content and full slots are displayed on the complete area of the video content. Note that full slot text ads are not yet supported.

AdTypes and their size specifications are summarized in the following table:

AdTypes and size specifications

AdTypes Descriptions Sizes
TEXT_FULL_SLOT If true, a close button is provided in addition to
the minimize button.
336 x 280
300 x 250
250 x 250
200 x 200
GRAPHICAL_FULL_SLOT
TEXT_OVERLAY If true, the ad minimizes after 60 seconds
or after the user clicks the minimize button.
320 x 60
GRAPHICAL_OVERLAY If true, the ad minimizes after 15 seconds
or after the user clicks the minimize button.
728 x 90
480 x 70
468 x 60
450 x 50

Refer to the API reference for a list of descriptions on ad type parameters or check Google AdWords Image Ad Formats for ad sizes.

Ad Types for VAST

Publishers working with VAST ads may use AdsRequestType parameters but are restricted to the following parameters:

Parameters VAST ad formats
VIDEO Linear
GRAPHICAL or OVERLAY Non-Linear

Refer to the IAB guidelines for further details on VAST ad serving.

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.