Rich Media Certification

Overview

Yahoo! accepts many Third Party Ad Vendors who offer rich media experiences such as expandable and floating ads. However, certification processes differ between sites and countries because of different ad serving platforms. Here are the four Yahoo! ad serving platforms:

1.) Standard XHTML ad calls

Examples: Yahoo! Front Page, Yahoo! News, Yahoo! Sports, Yahoo! Finance

2.) The DARLA ad platform (also known as Friendly-Iframe, Iframe-Busting or asynchronous ad serving) used on AJAX-powered sites

Examples: Yahoo! Mail Classic, Yahoo! Mail and media photo galleries

Yahoo! DARLA is IAB compliant (www.iab.net/ajaxrichmedia).

3.) The secureDARLA ad platform. This will eventually become the standard platform for all Yahoo! sites powered by AJAX.

Example: The all new Yahoo! Mail

4.) Standard Mobile ad calls

Example: Yahoo! WAP page, In-App

New Rich Media vendors undergo certification on all platforms. However, if you or your ad hosting vendor recently added the capability of serving Rich Media you will need to be certified because serving ads on the relevant Yahoo! sites is so much different. Please submit a request to eu-third-party-adserver at yahoo-inc dot com to begin the process.

To check if you or your vendor has been certified for a certain format or property please visit the individual ad specs pages. Formats outside our specifications or new formats delivered by 3^rd party vendors can’t be considered in the rich media certification.

DARLA Specifications

Guidelines for Rich Media Membership in the Ad Technology Program: Friendly iFrames Approach

This document provides information and sample code for the implementation of rich media ads on Yahoo! properties via friendly iframes.

Note: This approach is deprecated. If you’re implementing for the first time or modifying your implementation it’s best to adopt the expandable iframe approach, which is the preferred method also known as secureDARLA

What do you want to read about?

• Guidelines for the friendly iframe approach
• Code sample

In Ajax applications, the webpage is loaded only once and the content is dynamically updated with dynamic HTML (DHTML). Banner ads are periodically rotated in ad slots without reloading the page.

To help prevent JavaScript and DOM conflicts between the ad code and the Ajax implementation, Yahoo! serves the ads in iframes. However, expandable ads cannot be completely contained within an iframe, since the iframe would visually clip the expanded ad. The ads must have “iframe-busting” capabilities. The implementation gives the iframe access to the parent page, and the ads must:

1. Detect the iframe container.
2. Access the parent page.
3. Create a container in the parent page that is a sibling to the iframe container.
4. Hide the iframe container.

For an iframe-busting ad to work smoothly on an Ajax page, it must also listen on iframe unload events, which are triggered when another ad is rotated into the same slot or when the page is refreshed. Once triggered, the ad must completely remove any DOM components that it created, including the sibling container it created outside the iframe, and must restore the iframe container to its initial state.

We have created the following guidelines for creating expandable ads that will work smoothly with Yahoo! Ajax applications.

These guidelines cover the friendly iframe approach. This approach is now deprecated, but will be supported for some time to come. Support might vary depending on the Yahoo! property.

Framebusting

When the ad busts out of the iframe, it:

• Should write itself into the immediate parent container (parentNode) of the iframe.
• Should not attach or modify any DOM elements above and beyond the parent container.
• Should not rename or delete any pre-existing DOM elements.Note: When creating variable and function names, ensure there is no chance of collision with variables declared in global scope on the page by doing one of the following:
  • Use function closure to create a “local scope” for all of your JavaScript functions and variables, so that no variables are exposed to the publisher page.
  • If closures are not possible, use a single global name with common prefix to minimize the chance of collision with global scope.

Rotating the ad

When it’s time to rotate the ad, the Ajax implementation causes the iframe to unload. The ad must:

• Clean up after itself when the iframe unloads.
• Provide handlers for the iframe unload or beforeunload events.
• Restore the original state of the iframe and parentNode.Note: Be careful when using setTimeout(). The ad might be rotated away before the timer is activated. If that happens, the code should clear any timers that weren’t triggered.

Variables for expandable ads

Yahoo! has implemented two different variables for the expandable ad to detect:

• inFIF=true/false: this identifies whether the ad is in a friendly iframe. It can be used by itself or in conjunction with the isAJAX variable.
• isAJAX=true/false: this identifies whether the ad is in an Ajax environment.

For example, if inFIF is set to true but isAJAX is set to false, the ad is in a friendly iframe but is not within an Ajax environment.

Note: inFIF and isAJAX are Boolean variables defined in global scope within the iframe.

Essentially, your code must first use these two variables to detect that the environment is an Ajax implementation and that the ad is in a friendly iframe, and must then follow the guidelines above to instantiate and later close out the ad.

For an example of a rich media ad that uses code compliant with the Yahoo! proprietary Ajax implementation, see http://a6.fifa.ads.re4.yahoo.com/advendors/darla_demo.html. The example shows the same ad served to three different environments:

• Top left (click the button to view the ad): the ad is served to a Yahoo! page with proprietary Ajax implementation. A click expands the ad; another click closes the expandable area.
• Top right: the ad is served to a page that doesn’t support friendly iframes and doesn’t have the proprietary Ajax implementation. Because the container is an iframe and the ad cannot expand, a backup ad is served.
• Bottom: the ad is served to a page that supports friendly iframes but doesn’t have the proprietary Ajax implementation. A click expands the ad; another click closes the expandable area.

To view a sample ad with code that complies with the Yahoo! standard (the top left ad in the example above), see http://a6.fifa.ads.re4.yahoo.com/advendors/sample_code.html.

The ad code is shown below.

<script type="text/javascript">
/**
* Here we set up the ad content to use the old Yahoo! "friendly-iframe"
* model of expansion.
*
* We use an anonymous function wrapper so that the ad variables
* are not exposed and do not cause issues with other JavaScript.
*
* This model of expansion is being deprecated, but some websites
* may still be allowing or using this model.
*
* Only use this code if no Yahoo! sandbox API is detected.
*
*/

(function() {
  var win             = window,
    ad_in_frame       = (win != top),
    base_container    = null,
    ad_container    = null,
    can_access_top    = false,
    is_sandboxed      = !!(win.Y && Y.SandBox && Y.SandBox.vendor),
    is_friendly_frame   = false,
    is_ajax_env       = false,
    fif_inited        = false;

  // (code relating to the ad itself could be placed here)

  try {
    can_access_top  = !!(top.location.href);
  } catch (e) {
    can_access_top  = false;
  }

  /*
  * inFIF is a global variable that will be set inside the iframe
  * of ad content hosted by a Yahoo! property if the "friendly-iframe"
  * model of expansion is allowed. The best way to check for this is below.
  *
  */

  is_friendly_iframe  = (ad_in_frame && can_access_top && win.inFIF);

  /*
  * isAJAX is another global variable that will be set inside the iframe
  * of ad content hosted by a Yahoo! property if the "friendly-iframe"
  * model of expansion is allowed. Again the best way to check for
  * this is below.
  *
  */

  is_ajax_env     = (ad_in_frame && win.isAJAX);

  /*
  * The friendly-iframe model of expansion requires that a clean-up step
  * occurs when an ad is rotated / unloaded.
  *
  */

  function cleanUpAdAndRestoreIframe(container, friendly_iframe)
  {
    var par;

    try {
      /*
       * Remove the ad content parent node (this should
       * not include the iframe from which the ad was
       * originally served. )
       *
      */
      par = container && container.parentNode;
      if (par) par.removeChild(container);

      /*
       * Restore the iframe that ad was originally served
       * into
       *
      */

      if (friendly_iframe && friendly_iframe.style) {
        friendly_iframe.style.display = "block";
      }
    } catch (e) {
      //failed to clean up
    }
  };

  /*
   * Implements rendering of your ad content by placing it
   * into the parent document, and registering unload handlers
   * for cleaning up.
   *
  */

  function showAdThruFriendlyIframe(base_container)
    {
    var friendly_iframe,
      parElement,
      parDocument,
      unload_handler;

    try {
      /*
       * Always use a try / catch because the code
         * below will throw JavaScript errors if access is
         * not allowed, such as in the case of the Yahoo!
         * sandbox.
         *
        */

      friendly_iframe = win.frameElement;
      parElement      = friendly_iframe.parentNode;
      parDocument     = win.parent.document;

      if (!fif_inited) {
          /*
           * Note that the Opera browser is not supported
           * when using the "friendly-iframe" model.
           * So you could check for that browser and
           * exit if it’s detected.
           *
            */

        if (win.opera && (is_friendly_frame || is_ajax_env))
          throw new Error("Friendly IFrame not supported in Opera");

        /*
         * Set up an ad_container div element in the parent document that is
         * a sibling to the iframe in which the ad content was first hosted
         * All ad content (HTML/DOM element, JavaScript, etc.) should go into this div
         *
        */

        ad_container            = parDoc.createElement("DIV");
        ad_container.style.cssText  = "position:relative;width:300px;height:250px;";

        unload_handler        = function()
        {
          cleanUpAdAndRestoreIframe(ad_container, friendly_iframe);
        };

          parElement.insertBefore(ad_container, friendly_iframe);

        if (win.attachEvent) {
          //IE onunload

          win.attachEvent("onunload", unload_handler);

        } else {

          win.addEventListener("unload", unload_handler, false);
        }

          /*
           * Now hide the "friendly-iframe" in which ad content was originally served,
           * and set up your internal state to know that initialization was a success.
           * Always do this as the last step.
           *
          */

          friendly_iframe.style.display = "none";
          fif_inited            = true;
      }
    } catch (e) {
      /*
       * "friendly-iframe" initialization failed, do not allow
       * this mode of expansion.
       *
      */
      fif_inited      = false;
      is_friendly_frame = false;
    }
    if (fif_inited && is_friendly_frame) {
      showExpandableAd(ad_container);
    } else {
      //If an error occurs due to unsupported browser, or security exception

      showBackupImage(base_container);
    }
  }

  function showExpandableAd()
  {
    /*
     * Here you can expand your ad content using the reference
     * that was set from "friendly-iframe" initialization, if
     * it was successful.
    */

    if (ad_container) {

      /*
       * expand ad contents
       *
      */
    }
  }

  function showBackupImage()
  {
    /*
     * Here use the base container reference created in the loadAd function
     * to show backup content if the "friendly-iframe" model fails
     *
    */

    if (base_container) {

    }
  }

   /*
     * Base ad load function which detects the environment to determine appropriate
     * rendering strategy.
   */

  function loadAd(base_container_id)
  {
    base_container = document.getElementById(base_container_id);

    if (ad_in_frame) {
      if (is_sandboxed) {
        //Yahoo! Sandbox mode, use the above code samples

      } else if (is_friendly_frame || is_ajax_env) {
        //Yahoo! Friendly-IFrame Mode

        showAdThruFriendlyIframe(base_container);

      } else {

        //Not Yahoo! property, or no expansion supported

        showBackupImage(base_container);

      }
    } else {
      //ad is being rendered on the publisher document; so render directly.

      showExpandableAd(base_container);
    }
  }

  loadAd("fif_ad_demo_container");

})();

</script>

secureDARLA Specifications

Guidelines for Rich Media Membership in the Ad Technology Program

This document provides information and guidelines to help third party ad vendors meet ad code requirements to serve rich media ads on Yahoo! properties, prior to applying for membership in Yahoo!’s ad technology program.

It doesn’t explain how to write code to be compliant, but includes requirements, guidelines, and sample code.

This document has been updated to reflect the expandable iframe approach to rich media ad support.

What do you want to read about?

• Background
• Implementation
• General guidelines
• Basic API definition
• Code sample

Most Yahoo! properties include pages that use a proprietary implementation of AJAX (Asynchronous JavaScript and XML). This implementation allows portions of a webpage to reload without reloading the entire page. The AJAX pages rotate ads within iframes hosted on the same domain.

Rich media ads, such as expandable and floating ads, must be able to break out of the designated ad space, expanding or floating over other parts of the page. If a rich media ad is placed in an iframe, it must be able to break out of the iframe to perform correctly.

It’s important to make sure that the rich media ad code doesn’t conflict with the proprietary AJAX implementation, because a conflict might adversely affect the user experience on the page. For example, if the ad is replaced by a new ad before the page is refreshed, it’s important that the ad closes out neatly, removing any elements it created outside the iframe and leaving the page as it was before the ad was shown.

Third-party ad vendors must meet program membership requirements to help ensure their rich media ads will perform as expected on these pages, without adversely affecting the rest of the page or the user experience.

If rich media vendors would like to be or are approved for membership in the ad technology program, but they cannot meet the AJAX special requirements, their rich media ads will not be served to Yahoo! AJAX or friendly iframe pages.

Until recently, the recommended approach to the implementation of this technology on Yahoo! pages was by using “friendly iframes.”

Recent development has led to an improved approach to AJAX implementation on Yahoo! properties. This new approach involves expandable iframes that use a set of JavaScript methods to create expandable or floating ad content. This is known as the “expandable iframe” or “secure sandbox” model.

The new JavaScript methods are part of the new standard API that Yahoo! provides so that ad technology program members can create rich media ad code that uses this new technology for ads on Yahoo! properties.

Note: Implementation timelines might vary for different Yahoo! properties—both for adopting the new technology and for discontinuing support of the earlier approach.

It’s best for program members to move to the new approach as soon as possible, to take advantage of the new features and the new model of expansion. This new approach will be the de facto standard for Yahoo! in the future. However, it is up to the individual Yahoo! property, or other website to which the ad may be served, to determine the rules for that site.

Essentially, your code should test the environment and implement the expandable iframes approach as the default/first way to handle ad expansion if it’s available. If the expandable iframes approach isn’t available, the code should check if the friendly iframes approach is available, and use that if possible. Finally, if neither option is available, the code should treat the ad content as either non-expandable, or not on a Yahoo! site. This strategy will help ensure the best results for your ads.

The code sample given in this document shows how to implement this strategy so that all environments / setups work properly.

The eventual goal is that for all display ads on Yahoo! pages where JavaScript is enabled, the ads will be sandboxed inside a cross-domain iframe to prevent issues with page stability and security.

We strongly recommend that all new program members adopt the new approach, and that existing members transition as soon as possible. Although the earlier approach will be supported for some time to come, at some point support will be dropped.

The points below include general guidelines as well as general information about the expandable iframe approach to running expandable rich media ads on Yahoo! properties.

• If expanding in response to mouse over / mouse out events, make sure you call Y.SandBox.vendor.expand before you expand the ad contents. This is an asynchronous method. In order to ensure that you do not cause flickering or calculation issues, you should consider calling Y.SandBox.vendor.expand in one of two ways:
  • Call Y.SandBox.vendor.expand, and then use a timer, and expand your ad content. See sample code below.

    <script type="text/javascript"> function expandAD() { var yAPI = (window.Y && Y.SandBox) ? Y.SandBox.vendor || null : null, origWidth = 300, origHeight = 260; if (yAPI) { yAPI.expand(-100, -100); //iframe expansion command sent, give some time for it to //respond and then expand the ad setTimeout(function() { var el = document.getElementById("adcontainer"); el.style.width = (origWidth + 100) + "px"; el.style.height = (origHeight + 100) + "px"; }, 500); } } </script>

  • Register a call back function via Y.SandBox.vendor.register. Then when calling Y.SandBox.vendor.expand, this call back function will get called and you can respond and expand your ad. See sample code below.

    script type="text/javascript"> function handleYMsg(msg) { var el; if (msg == "expanded") { el = document.getElementById("adcontainer"); el.style.width = (origWidth + 100) + "px"; el.style.height = (origHeight + 100) + "px"; } } function setupAd() { var yAPI = (window.Y && Y.SandBox) ? Y.SandBox.vendor || null : null, origWidth = 300, origHeight = 260; if (yAPI) { yAPI.register(origWidth, origHeight, handleYMsg); } } function expandAD() { var yAPI = (window.Y && Y.SandBox) ? Y.SandBox.vendor || null : null, origWidth = 300, origHeight = 260; if (yAPI) { yAPI.expand(-100, -100); //iframe expansion command sent, now wait for callback //(goto handleYMsg) } } /script>

  • Always provide some obvious way for the user to close the ad contents. This is particularly important because users will not be able to click on anything behind the ad in the hosting webpage.
  • If the Y.SandBox.vendor API exists, this confirms that you are inside a cross-domain iframe. It also means that you can use an onunload handler to clean up if needed.
  • The Y.SandBox.vendor API is available as soon as your ad contents render. However, ads that have nested iframe tags might not be able to call this API. If the API is not available, and the old “friendly iframe” global JavaScript variables (inFIF or isAJAX) are not present, expansion of any kind will not work.
  • Do not attempt to use iframe-busting or policy files. These are not supported on Yahoo! properties.

Below is the current definition of the JavaScript API that program members can access to provide interaction with the webpage. The only action currently supported is the expansion feature for expandable or floating ads; however, more features will be added later.

There are three functions:

• Y.SandBox.vendor.register( {Number} width, {Number} height, {Function} cb)
• Y.SandBox.vendor.expand( {Number} dx, {Number} dy )
• Y.SandBox.vendor.collapse()
• Y.SandBox.vendor.geom()

Y.SandBox.vendor.register( {Number} width, {Number} height, {Function} cb)

Call this function once to register with the webpage for communication.

Parameters are listed below.

Y.SandBox.vendor.expand( {Number} dx, {Number} dy )

Call this function when you want your ad contents to grow. It should be called prior to changing your ad content size, such as in cases of expansion or floating ad contents. The ad is only allowed to grow in one direction for width and one direction for height.

The code sample below modifies the ad width and height to grow by 100 pixels; if the top left corner was previously at 0,0 it changes to -100, -100.

You must call Y.SandBox.vendor.register once before calling this method.

Parameters are listed below.

Y.SandBox.vendor.collapse()

Call this function when you want the ad contents to reset to the original size state. Call this method prior to adjusting your contents.

Y.SandBox.vendor.geom()

Call this function when to retrieve geometric information about the browser window, and HTML elements surrounding your ad. You can use this information to determine the direction your ad should expand and by how much. The return value from this function is a JavaScript Object with 4 separate properties, each representing dimensions of particular browser areas that are related to the ad.

The properties of this object are listed below.

Below is some example usage of this function.

function expandAD()
 {
      var yAPI = (window.Y && Y.SandBox) ? Y.SandBox.vendor || null : null,
         info, origWidth = 300, origHeight = 260, defaultExpT = -100,
         defaultExpL = -100, t, l;

     if (yAPI) {
         try {
             info = yAPI.geom(); //Always use a try/catch as
                                 //this method is not available in
                                 //older versions

              t = info.exp.t;
              l = info.exp.l;
              if (t < defaultExpT) t = defaultExpT;
              if (l < defaultExpL) l = defaultExpL;
          } catch (e) {
              info = null;
              t    = defaultExpT;
              l    = defaultExpL;
          }

         yAPI.expand(l, t);

         //iframe expansion command sent, now wait for callback
         //(goto handleYMsg), new width will be 400 x 360, with the
         //top / left coordinate shifted by -100 pixels 

     }
 }

The ad code sample below shows how to write JavaScript code for an expandable ad. This example works for the new “sandbox / expandable-iframe” model and also for the earlier “friendly-iframe” approach.

As noted previously, the friendly iframes approach will be supported for a while, but in the future it will no longer be allowed. At that time, use of the JavaScript API provided by Yahoo! will be required.

The sample code below shows how to provide expandable ad functionality by detecting the ad’s environment and then determining how to expand.

<script type="text/javascript">
/**
* Sample JavaScript code that ad technology program members can add to their pages to
* support expandability from within Yahoo!’s sandboxed mode.
*
* Place this code as the last set of lines in your JavaScript code for your ad content.
*/

var win                = window,

    /*
     * Check for the Yahoo! sandbox. Below is the best way to do this
     * otherwise you may cause JavaScript errors.
    */

    bIsYSandboxed      = !!(win.Y && Y.SandBox && Y.SandBox.vendor),

    /*
     * Check for the Yahoo! old "friendly-iframe" mode. Some sites may
     * still be allowing / using this methodology of expansion. Again below
     * is the best way to do this.
    */

    bIsFIF             = !!(win.inFIF || win.isAJAX),

    bCanExpandSandbox  = false,

    expandTimerID      = 0;

/**
*
* Run this function once, like you would in an onload handler
*
*/

function register_for_expansion()
{
  var canTalkToTop = false;

  /*
   * Check and see if ad is running inside a sandbox that
   * can be accessed. ALWAYS do the check like this, using
   * a try / catch block, or you may see JavaScript errors.
   *
  */

  try {
     canTalkToTop = !!(top.location.href);
  } catch (e) {
     canTalkToTop = false;
  }

  /*
   * 1st always check for the new Yahoo! API, as that’s the new standard.
   * If it’s there use that for communicating expansion to the webpage.
   *
  */
  if (bIsYSandboxed) {
    try {
      /*
       * These are the default width / height numbers of the ad position
       * content. In this example we are using the standard LREC size.
       *
      */

      Y.SandBox.vendor.register(300, 268,  handle_api_updates);
      bCanExpandSandbox  = true;

    } catch (e) {
      bCanExpandSandbox  = false;
    }

    /*
     * DO NOT attempt to inspect the top or parent windows
     * if inside the Yahoo sandbox. (Event if expansion is not working).
     * as this will result in errors.
    */

  } else if (bIsFIF) {
    /*
     * Fallback to the Yahoo! "friendly-iframe" setup for expansion here.
     * Note that talking to the top / parent window references in this
     * case is allowed.
    */

  } else {
    /*
     * No Yahoo! supported expansion is allowed
     * Note also the Yahoo! does not support the iframe policy model
     * of expansion (i.e. DoubleClick's DARTIframe.html setup).
    */
  }
}

/*
* Optionally, you can specify a callback function when you register

* with the Yahoo! sandbox, to receive notification in certain
* scenarios.
*
*/

function handle_api_updates(msg)
{
  if (bCanExpandSandbox) {
    if (msg == "collapsed") {
      /*
       * The sandbox has been collapsed from the outside (i.e. by the hosting webpage).
       * Re-set your internal ad content.
      */

    } else if (msg == "expanded") {
      /*
       * You made a call to Y.SandBox.vendor.expand, and it has succeeded.
       * Here you should expand the internal ad content.
      */

    }
  }
}

/**
*
* The next 2 functions below are event handlers
* that are just examples ad technology program members can use.
* In this example we assume that when some ad content is in the "hover" state,
* we want the ad to grow/expand.
*
*/

function handle_mouseover()
{
  /*
   * we already send an expansion command,
   * so do nothing
  */
  if (expandTimerID) return;

  if (bCanExpandSandbox) {
    try {
      /*
       * This call will grow the ad position to the left by 300px, and down 300px.
       * This doesn't need to be exact, just make it big enough.
       * Note that this call is asynchronous, which means that expansion of the
       * ad are will not happen immediately.
      */

      Y.SandBox.vendor.expand(-300, 300);

      /*
       * Because the above call is asynchronous, we have 1 of 2 options.
       * 1.) Use a timer, and trigger the internal ad content to expand, allowing
       *     enough time so the call above is received by Yahoo.
       *
       * 2.) Provide a callback function to the Y.SandBox.vendor.register function
       *     and wait for that function to be executed with the "expand message.
       *
       * For simplicity will just use a timer.
      */

      expandTimerID = setTimeout(function()
      {
        /*
         * If the expansion timer is not set anymore it means that expansion
         * was canceled, probably from a mouse out event. So do nothing
        */

        if (!expandTimerID) { return; }

        /*
         * We set the timer id to 0, so that we know that it has been
         * executed
        */

        expandTimerID = 0;

        /*
         * Now in here we expand the internal ad contents
         *
        */

      }, 250);

    } catch (e) {

    }
  } else if (bIsFIF) {
    /*
     * The Yahoo! sandbox is not available. So we check
     * if the "friendly-iframe" model can be used.
     *
    */

  } else {
    /*
     * No Yahoo! system detected, so no expansion on Yahoo! sites is
     * allowed. So here do whatever fallback method you may have.
    */
  }
}

function handle_mouseout()
{
  /*
   * Clear the timer that we set up earlier
   *
  */

  if (expandTimerID) {
    clearTimeout(expandTimerID);
    expandTimerID = 0;
  }

  if (bCanExpandSandbox) {
    try {
      /*
       * This method is also asynchronous, but you don't
       * have to wait for it. You can just call collapse
       * to collapse the sandbox and collapse the internal
       * ad content immediately
       */

      Y.SandBox.vendor.collapse();

      //reset your ad content to be sized for the original
    } catch (e) {

    }
  } else if (bIsFIF) {
    //if need be do your normal "friendly-iframe" reset code here
  }
}

  setTimeout(register_for_expansion, 1000);
</script>