AdSense for video (AFV)

Technical quick start guide

A getting started guide for engineers using the Google IMA SDK to serve AdSense ads in Flash.

A brief overview

AdSense for Video and AdSense for Games operate using the same Google product- the Interactive Media Ads Software Development Kit (IMA SDK). This SDK allows you to request AdSense ads through Flash’s ActionScript language in order to more closely combine content and advertising. These products are subject to the AdSense Terms & Conditions, AdSense Program Policies, and product-specific usage guidelines. Remember that inadvertent clicks originating from overly aggressive or faulty implementations will result in action up to (and including) account termination.

Requesting and rendering ads through the IMA SDK is a matter of setting up an ad request, loading the resultant ad, and playing it at the right time. You can test using the default publisher IDs “ca-video-afvtest” or “ca-games-test”. You will need to provide your account manager with an example of your integration before you are allowed to deploy ads to your site(s).

Installation

You need to begin by downloading the Google IMA SDK SWC or MXP library. This library is inserted into your Flash or Flex installation and gives you access to the SDK’s functionality. Be sure to follow our installation instructions found here.

Example code

Wherever you plan to implement the IMA SDK, you’ll need to make sure that you’ve added the necessary include statements.

Ad request setup

You need to create an ad request with contextual targeting parameters, channels, your publisher ID, and other necessary parameters. Once the ad request object is prepared, an ads loader is necessary to manage the ad request and to direct the ad response to a method to handle the callback. When an ad is successfully returned the AdsLoadedEvent.ADS_LOADED event is triggered while if an ad request is unsuccessful then the AdErrorEvent.AD_ERROR event is triggered.

There are additional APIs available in our full API guide.

Parameters

Required

These are parameters that are required for every ad request. Ad requests will fail without these parameters included and well-formed.

Name Type Description
adSlotWidth Number The width of the area that the ad will be placed into measured in pixels.
adSlotHeight Number The height of the area that the ad will be placed into measured in pixels.
publisherId String Your account ID for the AdSense for Video or AdSense for Games product.
Note: Be sure to format your publisherId as "ca-games-pub-0123456789012345" or "ca-video-pub-0123456789012345".
Note: Be sure to use the "ca-video-afvtest" or "ca-games-test" publisherId while testing.
contentId String Any unique alpha-numeric string that is specific to a video or game. This ID string should not be repeated across different pieces of content. This is used in ad targeting as well as policy reviews.
Example: YouTube uses a VideoId in order to distinguish between videos ("0aRIlnQzw-A").
adType adRequestType The type of ad being requested.

Values

  • AdsRequestType.AUDIO Audio ads, comprised of a linear audio clip and a companion banner.
  • AdsRequestType.FULL_SLOT Rectangular advertisements suitable for use before game content or after video content.
  • AdsRequestType.GRAPHICAL Display overlay or fullslot ads (image/flash only).
  • AdsRequestType.GRAPHICAL_FULL_SLOT Display fullslot ads (image/flash rectangular ads only).
  • AdsRequestType.GRAPHICAL_OVERLAY Display overlay ads (image/flash banner ads only).
  • AdsRequestType.OVERLAY Banner advertisements with animation suitable for use during video content.
  • AdsRequestType.TEXT_FULL_SLOT Text fullslot ads (text content only).
  • AdsRequestType.TEXT_OR_GRAPHICAL Fullslot or overlay ads of any kind.
  • AdsRequestType.TEXT_OVERLAY Text overlay ads (text content only).
  • AdsRequestType.VIDEO Video pre-roll, mid-roll, or post-roll ads.

Recommended

These are parameters that are not technically required during the ad request process, but can significantly enhance your revenue and reporting when properly configured.

Name Type Description
channels String[] An array of channel ID strings that is used in reporting and ad targeting. These can be either channel strings as defined by your account manager or 10 digit numbers for channels that you create in the AdSense interface. Read more about channels here.
descriptionUrl String The full URL of an HTML document with a description of the video or game content that the ad will be served with. Be sure that the document is well-formed and is free of style elements or non-related content.
Example:
<html>
    <head>
    <title>Domain.com - Your tag line here!</title>
    </head>
    <body>
    <h1>Descriptions</h1>
    <h2>About this Content</h2>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. ...</p>
    <h2>About Domain.com</h2>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. ...</p>
    </body>
</html>
age Number A number representing the approximate age of the user.

Values

  • 1000 Represents persons 17 years old and younger.
  • 1001 Represents persons 18 to 24 years old.
  • 1002 Represents persons 25 to 34 years old.
  • 1003 Represents persons 35 to 44 years old.
  • 1004 Represents persons 45 to 54 years old.
  • 1005 Represents persons 55 to 64 years old.
  • 1006 Represents persons 65 years old and older.
gender Number A number representing the gender of the user.

Values

  • 1 Represents a male user.
  • 2 Represents a female user.

Optional

These parameters are optional and useful for tweaking how ads are requested or rendered.

Name Type Description
adtest String A useful testing parameter that, when enabled, will disregard impressions and clicks on a publisher ID. This will allow you to inspect live ads without charging advertisers.

Values

  • on Impressions and clicks are disregarded.
  • off (Default) Impressions and clicks are counted normally.
uniqueAds Boolean When enabled, ads for a single page load will be unique. This is useful for frequency capping for a single video or game.
adTimePosition Number This value establishes when the video ad is being shown in a content stream.

Values

  • 0 (Default) The ad is being shown in a pre-roll position before the content.
  • -1 The ad is being shown in a post-roll position after the content has finished.
  • N The number of seconds into the content stream that the mid-roll ad is being played.

Callbacks

These callbacks can be subscribed to in order to recieve notification of important ad loading events.

Name Description
AdsLoadedEvent.ADS_LOADED This event is fired when an ad request has been made and returned successfully with one or more individual ad units ready to be loaded and rendered.
AdErrorEvent.AD_ERROR This event is fired when an ad request has been made and returned unsuccessfully with either malformed parameters or if an ad is not available.
Note: Ads may not be returned for a variety of reasons, and your integration must be able to accomodate this scenario gracefully.

Example code

In order to request an ad, you must prepare an ad request with relevant parameters.

var adsRequest:AdsRequest = new AdsRequest();

// Required parameters
adsRequest.adSlotWidth = 640;
adsRequest.adSlotHeight = 360;
adsRequest.publisherId= "ca-video-afvtest";
adsRequest.adType = AdsRequestType.VIDEO;
adsRequest.contentId = "0aRIlnQzw-A";

// Recommended parameters
adsRequest.channels = ["sports", "entertainment", "0123456789"];
adsRequest.descriptionUrl = "http://www.example.com/description.htm";
adsRequest.age = 1002;
adsRequest.gender = 1;

// Optional parameters
adsRequest.adTest = "on";
adsRequest.language = "ja";
adsRequest.maxTotalAdDuration = 30000;
adsRequest.minTotalAdDuration = 15000;
adsRequest.uniqueAds = true;
adsRequest.adTimePosition = 1;

// Prepare the ads loader
var adsLoader:AdsLoader = new AdsLoader();
stage.addChild(adsLoader);

// ADS_LOADED for when ads are successfully returned
// AD_ERROR for when no ads were found for the request
adsLoader.addEventListener(AdsLoadedEvent.ADS_LOADED, onAdsLoaded);
adsLoader.addEventListener(AdErrorEvent.AD_ERROR, onAdError);

// Request the ads
adsLoader.requestAds(adsRequest);

Ad rendering

Once an ad request has resolved to a response, your code will need to be able to either render the ad appropriately or fall back to another ad source or the content. Be sure that your integration is event-driven and does not rely on timers to handle ad rendering.

Before submitting your integration for approval, be sure to confirm that your ad rendering is compliant with our product-specific usage guidelines.

There are additional APIs available in our full API guide.

Properties

These are properties of the AdsManager that can be used to change how ads are rendered.

Name Type Description
adSlotHeight Number Sets or gets the height of the rectangular area within which an ad is displayed. This value does not need to match the actual ad's height, but should be at least as large as the ad's height. You should set a new value whenever ad slot changes it's dimensions, for example a video player might have video controls that fade in and out, changing the available area for the ad slot.
adSlotWidth   Sets or gets the width of the rectangular area within which an ad is displayed. This value does not need to match the actual ad's width, but should be at least as large as the ad's width. You should set a new value whenever ad slot changes it's dimensions, for example a video player might have video controls that fade in and out, changing the available area for the ad slot.
ads ad[] An ad list that stores data about individual ads that are returned by the ad server. You can access every ad via this method.
type String Returns the type of ad(s) that was returned.

Values

  • flash Overlay and fullslot ads.
  • video Video ads.
flashAdsManager Only
decoratedAd Boolean If true, the ad will be displayed with Google-provided chrome as applicable to the type of ad, such as a close button, reopen pill, show/hide animations, and background.
volumeAd Number Sets or gets volume for an ad that supports audio.
x Number Sets or gets Flash ad(s) display area's coordinate. If ad is smaller than the area for displaying the Flash ad, then the alignment value is also used to best position the ad.
y Number Sets or gets Flash ad(s) display area's y coordinate. If ad is smaller than the area for displaying the Flash ad, then the alignment value is also used to best position the ad.
videoAdsManager Only
clickTrackingElement InteractiveObject Click tracking must be enabled on the video player area before the ad can be played. This property allows getting and setting the element on which clicks are tracked.
mediaSelectionSettings MediaSelectionSettings This property gets and sets the media selection settings set by users. Media selection settings are used to choose which media files are used in the video ads since the ads may contain URLs for multiple media files. You can specify which bandwidths, mime types and delivery modes they support/prefer. This property is ignored for ads that do not contain multiple media files.

Methods

These are methods that can be invoked on the ad manager in order to invoke ad loading and rendering.

Name Description
(void) load(container?:Object) This method allows ads to pre-load assets to get ready for display. Video ads are pre-buffered while assets for Flash ads are downloaded. Ads aren't displayed until play() has been called. The container object is only necessary for video ads and is not necessary for Flash ads.

Values

  • Video Uses NetStream to pre-buffer and play the video ad.
  • FLVPlayback Uses the FLVPlayback component to pre-buffer and play the video ad.
(void) play(container?:Object) Ads are displayed when this method is invoked. Flash ads do not require any parameter because Stage is used as display area by default. Video ads require a container object parameter since they are played in the publisher's video player.

Values

  • Video Uses NetStream to pre-buffer and play the video ad.
  • FLVPlayback Uses the FLVPlayback component to pre-buffer and play the video ad.
  • DisplayObjectContainer Uses DisplayObjectContainer to render the Flash ads. Positioning is relative to the display object container provided. Once the display object container is provided, it can't be changed.
(void) unload() Ads might have assets loaded at runtime that need to be properly removed at the time of ad completion. This is especially true for Flash ads where unload results in assets removal from the display list. It is recommended to call unload when the ad has been displayed and will not be used anymore.

Callbacks

These are subscribable events.

Name Description
AdEvent.CONTENT_PAUSE_REQUESTED This event is called when the video player or game is required to pause the content (usually as a result of a click or the beginning of a linear ad).
AdEvent.CONTENT_RESUME_REQUESTED This event is called when the video player or game is allowed to resume the content (usually as a result of the completion of a linear ad).
AdEvent.CLICK This event is called when an ad has been clicked.
AdEvent.STARTED This event is called when an ad has been started.
AdEvent.PAUSED This event is called when an ad has been paused.
AdEvent.STOPPED This event is called when an ad has been stopped.

Example code

The resulting ad must be loaded and rendered.

function onAdsLoaded(adsLoadedEvent:AdsLoadedEvent):void
{
    // Get 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)
    {
        // Create the video ads manager.
        var videoAdsManager:VideoAdsManager = _adsManager as VideoAdsManager;

        // Set a visual element on which clicks should be tracked for video ads
        videoAdsManager.clickTrackingElement = <object>;

        // Wire important events
        videoAdsManager.addEventListener(AdEvent.COMPLETE, onVideoAdComplete);
        videoAdsManager.addEventListener(AdEvent.CLICK, onVideoAdClicked);

        // Play back the ads.
        _adsManager.load(<flvPlayback>);
        _adsManager.play(<flvPlayback>);    
    }
    else if (_adsManager.type == AdsManagerTypes.FLASH)
    {
        // Create the flash ads manager.
        var flashAdsManager:FlashAdsManager = _adsManager as FlashAdsManager;

        // Play back the ad.
        flashAdsManager.load(this);
        flashAdsManager.play(this);
    }  
}
function onAdError(adErrorEvent:AdErrorEvent):void
{
   log("Ad Error: " + adErrorEvent.error);
   // Play Content
}

Companion banners

Companion banner code can be inserted into your page and allow you to show a related text, image, or flash ad while rendering a video ad. These companion ads sometimes unlock additional revenue by allowing more advertisers to compete in the auction. However, they are optional.

There are two ways of displaying AdSense for Video or AdSense for Games companion banners.

Embedding into HTML

AdSense for Video and AdSense for Games have specific requirements about how SWFs are embedded into HTML. Most importantly, allowScriptAccess must be set to “always.” This allows the AFG system to detect the URL of the page making the ad request. Ads will not be served on games where we cannot detect the URL. We need to be able to detect the page URL so that we can report information to advertisers on where their ads are being displayed. The page URL is also used for policy review purposes and to improve contextual ad targeting.

If you are using standard HTML tags to embed your game player, you must include both the <object> and <embed> tags in order to properly set allowScriptAccess in both IE (using the <object> tag) and Firefox (using the <embed> tag).

Example code

<object width="320" height="240" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
       id="NeedThisParam">
    <param name="movie" value="http://www.example.com/v/?i=11149286"
       type="application/x-shockwave-flash"></param>
    <param name="allowScriptAccess" value="always"></param>
    <param name="wmode" value="transparent"></param>
    <embed src="http://www.example.com/v/?i=11149286"
          type="application/x-shockwave-flash"
          allowScriptAccess="always"
          width="320"
          height="240">
    </embed>
</object>