Developing Ad Translators

Ad translators are available only for Brightcove Pro and Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.

This document describes how to create an Ad Translator. The Ad Translator enables easy integration between Brightcove players and ad servers. By default, Brightcove players are set up to integrate with DoubleClick DART for Publishers. In addition, using the Advertising module, you can set your players to integrate with a number of ad translators for other ad servers. With the Ad Translator, you can integrate your Brightcove players with just about any ad server. Here's the basics of how it works:

• The Ad Translator is a Flash SWF file that is loaded at runtime by a Brightcove player and acts as a proxy for ad requests between the players and an ad server.
• You can use the Ad Translator for an individual player, or at the account level for all your players, including any virally distributed or syndicated players.

Integration between Brightcove players and non-DFP ad servers previously required custom development, using the Brightcove APIs. Once you've created the Ad Translator SWF, you don't need to use the APIs to support non-DFP ad integrations, as long as you're using a Brightcove-supported ad format. The Brightcove APIs are still required to play back custom ad formats or to play back ads outside the player.

Brightcove is developing a set of Ad Translators for most major ad servers. See Brightcove Ad Integrations for a list of Ad Translators available as of the date of this release. Contact your Account Manager or Customer Support to see if we already have an Ad Translator you can use before you start to develop your own.

Ad Translator: Main Steps

In order to enable your account for integration with the Ad Translator, you should:

1. Create an Ad Translator class and compile it into a SWF, as described in Creating an Ad Translator SWF.
2. Host the Ad Translator SWF on your domain.
3. To test the Translator you've developed, you can set the Ad Translator path at the player level in the Brightcove Advertising module. For details, see Setting the Ad Translator.
4. Once you've completed testing and if you'd like to make the Ad Translator the default for all the players in your account, contact Brightcove Support to set the translation SWF path for your publisher account. 

Using the Ad Translator

To use the Ad Translator, you need to understand what your particular ad server requires in an ad request and what data it returns in response to the ad request. This is independent of any Brightcove implementation and will differ per ad server and often per configuration of an ad server. The framework for the Ad Translator that Brightcove provides allows a SWF, using standard ActionScript, to be informed when an ad request is made by a player and provides the context of the player at the time of the ad request. All communication with the ad server and parsing of the response is handled by the client through the Ad Translator.

An Ad Translator SWF needs to perform two basic tasks:

• Make an ad request to your ad server
• Take the XML ad response from the ad server and creates an ad from it.

Flash security features constrain a Flash player's ability to interact with files on other domains. You need to modify your site's crossdomain.xml file to permit your players to access the domain that hosts your Ad Translator. See Crossdomain security settings for Ad Translators.

Creating an Ad Translator SWF

You can start your Ad Translator development with our example file, Example.as. You can download Example.as and bc_ads.swc, an external library for Ad Translators, in a zip file. In addition, the zip file includes an API reference for the AdContext, AdTranslation, and TranslationURLLoader classes.

Creating an Ad Translator in Flash Authoring

1. Create a new ActionScript .fla file using Adobe Flash CS3.
2. Create a directory folder that includes your .fla file, and the Example.as and bc_ads.swc files from the example zip, AdSDK.zip.
3. Set Example.as your Document class, either in the Properties panel in the Flash IDE or by navigating to File > Publish Settings > Flash tab > Actionscript 3.0 Settings.
4. Edit the Example.as file, modifying the fetchAd and onAdLoad functions as needed for your ad server.
5. Making sure bc_ads.swc is in the same directory as your translator .fla file, publish your .fla (CTRL + Enter). The bc_ads.swc external library allows ad translators to be compiled without including extra bulk that would affect SWF file size.
6. The .fla should compile successfully and output a SWF in the same directory as your .fla file.
7. Host the Ad Translator SWF on a web server where it can be accessed by your players.
8. Set the Ad Translator URL for a player. In the Advertising module, select one of your players, set the Ad Translator to Custom and enter the URL of your Ad Translator.

When you request an ad with this player, you should see a Henderson's video ad.

Creating an Ad Translator in Flex Builder

1. Create a new ActionScript project. On the first screen, change the Project contents folder to the location of the example source files. Click Next.
2. On the second screen, change Main source folder to an empty string.
3. Click on the Library path tab, click on Add SWC, and add bc_ads.swc.
4. Change Main application file to Example.as and click Finish.
5. Right-click on the project and select Properties. Click on ActionScript Properties and then add the following under Additional Compiler Options: "-load-externs bc_ads_extern.xml".
6. Edit the Example.as file, modifying the fetchAd and onAdLoad functions as needed for your ad server.
7. After building the project, you should have a file named Example.swf in the bin-debug folder.
8. Host the Ad Translator SWF on a web server where it can be accessed by your players.
9. Set the Ad Translator URL for a player. In the Advertising module, select one of your players, set the Ad Translator to Custom and enter the URL of your Ad Translator.

When you request an ad with this player, you should see a Henderson's video ad.

The Ad Translator class file

Examine Example.as and see how it implements the basic structure for an Ad Translator:

1. The ad tag translation class is an ActionScript 3.0 Flash class that extends com.brightcove.fl.advertising.translation.AdTranslation.
2. The ad tag translation class relies on bc_ads.swc, which should be added an an external library.
3. In the class constructor, you can add event hooks into the player or load anything else that would be needed for ad translation.
4. The most important functions are fetchAd(), which makes the ad request, and onAdLoad(), which parses the response and acts on it to display the ad.

Making the ad request

Your Ad Translator class must override the fetchAd() function. This is the key function that makes the ad request. Within fetchAd(), construct the ad URL and send it to the ad server using com.brightcove.fl.advertising.translation.TranslationURLLoader. This function must be included, and in the same form, though its contents will differ based on the ad server implementation. When an ad is requested, the player calls this function and passes an instance of AdContext. The AdContext object is a collection of properties that define the current state of the player at the time of the ad request. Properties include video, cue point, key/value pairs, etc. See the AdContext object in the Ad API Reference for a complete list of the properties that can be set in the AdContext object.

The fetchAd() function in the example looks like this:

override public function fetchAd(context:AdContext):void {
    // Create the URL with the ad-related parameters
    var url:String = createAdRequestURL(context);
    trace("Created the ad url: " + url);
           
    // Request the ad, sending the response to the onAdLoad function 
    //loader.load(url, onAdLoad, onAdLoadError);
 
    // Usually you would just call loader.load() at this point, as shown directly above. 
    // But since this is an example where we don't have a real ad server to call, we have 
    // to create our own ad locally and call onAdLoad() directly
    var fakedResponse:String = "<videoAd version='1' duration='15' houseAd='true'>" + 
        "<videoURL>http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv</videoURL>" + 
        "</videoAd>";  // line that's just for the example
    onAdLoad(fakedResponse); // line that's just for the example
} 

This fetchAd() function uses a createAdRequestURL() function to put together the ad request; you could instead build the ad request in the fetchAd() function. Here is what the createAdRequestURL() function in the example looks like:

private function createAdRequestURL(context:AdContext):String {
    // first get the ad server URL 
    var adServerURL:String = context.adServerURL;
    // combine all the custom key/values
    var userKeyValues:String = "";
    if (context.playerKeyValues) userKeyValues += DELIM + context.playerKeyValues;
    if (context.titleKeyValues) userKeyValues += DELIM + context.titleKeyValues;
    if (context.insertionKeyValues) userKeyValues += DELIM + context.insertionKeyValues;
    if (userKeyValues.length > 1) userKeyValues += DELIM;
    // You should convert any ";" separators to the ad server's delimiter. 
    // In the example case,the pretend ad server's delimiter is ';', so technically
    // this next line isn't needed here 
    userKeyValues = userKeyValues.replace(/;/g, DELIM); 
    // Tell the ad server about the current formats
    var adFormats:String = "";
    for(var i:Number = 0; i < context.adFormats.length; i++) {
      adFormats += "frmt=" + context.adFormats[i] + DELIM;
    }

    // The cue type:  onLoad, Pre-roll, Mid-roll, or Post-roll
    var cue:String = context.type;
    if (cue == AdContext.CUE) {
      cue = context.cuePoint.name;
    }
    cue += DELIM;
  
    // The player ID
    var playerID:String = "plID=" + context.playerID + DELIM;
    // A timestamp at the end of the call
    var timestamp:Number = (new Date()).getTime();
    var ord:String = "ord=" + timestamp + DELIM;
  
    var url:String = adServerURL + userKeyValues + adFormats + cue + playerID + ord;
    return url;
}

Within the load and error callback functions, your Ad Translator class needs to transform the response into XML and call setAdXML().

Handling the ad response

Within the fetchAd() function, you usually will use TranslationURLLoader to call an ad server. The call will look something like this:

loader.load(url, onAdLoad, onAdLoadError);

The first parameter in the load() call is the URL that was set up earlier. onAdLoad and onAdLoadError are functions that handle a load response or an error response. So you need to create a function in your Ad Translator named onAdLoad that parses the data returned from the ad server. If the data returned is not already in XML format, the data must be placed into an ActionScript XML object and passed back into the player through setAdXML(). The Brightcove players accept only XML input coming from your Ad Translator. The ad XML must be in one of the pre-defined supported formats described in Supported Ad Formats. When constructing your ad XML, keep in mind that some fields may not be required by your ad server. For instance, OAS tracks an impression as soon as the ad is served, which means that only the trackStartURLs attribute is required for third party tracking.

How you parse the ad response depends on the exact form that the ad server sends it in and won't be addressed here. Here is the onAdLoad() function in the example Ad Translator:

public function onAdLoad(str:String):void {
  var xml:XML = null;
  try {
    xml = new XML(str);
  } catch (err:TypeError) {
    // ignore, but xml will be null
    trace("Could not convert ad data into XML."); 
  }
  // any conversion of the returned XML into Brightcove's format should go here
  // tell the player that we are done processing
  setAdXML(xml);
}

If onAdLoad() is not called, the player will not regain focus and the ad and video content will not play. Note: If no ad is to be played, simply pass null in the onAdLoad() call.

Using Third Party Redirects

You can use the Ad Translator in conjunction with a third party redirect to tell the Brightcove player to make an additional ad call to a third party ad server. The third party redirect is not a standard server-side or client-side redirect; rather it is an XML instruction specific to Brightcove players. It takes the form:

<requestThirdPartyAd translationSWF="http://mysite.com/adtranslator.swf" [trackingPixel="ad_server_impression]">
    <optionalArg1>SomeValue</optionalArg1>
    <optionalArgN>AnotherValue</optionalArgN>
</requestThirdPartyAd>

An ad server can return the <requestThirdPartyAd> XML instruction in response to an ad call from the Brightcove player. When the Brightcove player sees the root node <requestThirdPartyAd> in the ad response, it knows that the data does not contain an ad, but an instruction to make a new call.

You can add as many XML nodes to the third party Ad request as you like, including an optional trackingPixel.

Within the Ad Translator, the XML can be accessed via a property in the AdContext named thirdPartyAdXML. The Ad Translator SWF constructs a complete ad call for the specified ad server, and awaits an XML response. The Brightcove player makes a request for trackingPixel as soon as the third party ad request is made. Note that this trackingPixel is in indicator of the number of ad requests sent to the third party ad server; it does not track the number of successful ad impressions.

The <requestThirdPartyAd> XML can contain an additional arbitrary number of parameters that your Ad Translator can act upon. For example, you can insert a parameter for the URL like this:

<requestThirdPartyAd translationSWF="http://mysite.com/adtranslator.swf">
    <url>http://myadserverURL/mypath/</url>
</requestThirdPartyAd>

In this example, the Ad Translator can retrieve the URL value from the third party Ad XML like this:

override public function fetchAd(context:AdContext):void {
    // Get the ad URL from the XML in requestThirdPartyAd
    var adServerURL:String = context.thirdPartyAdXML.url;
}

Then parse the XML and modify the resulting ad request appropriately.