Developing Ad Display SWFs

Creating an Ad Display SWF requires advanced development skills. This feature is intended for use by ad network and ad serving partners with complex ad delivery requirements. If you are a Brightcove customer and think your project or product calls for use of the Brightcove Ad Display SWF, please first contact your Account Manager to see if one of Brightcove's ad partners would work better for you.

This document describes how to create an Ad Display SWF. By default, a Brightcove player expects ads to be returned in XML format. Using an Ad SWF enables the use of Flash SWF-based ad components or modules. This opens up many possibilities for how an ad can look and behave.

If you want to deliver/render a unique Ad Format in your Brightcove player, that is not one of Brightcove's standard Ad Formats, you can develop your own Ad Display SWF.  The Ad Display SWF is an advanced tool which is often used for development by advertising partners.

Just like other ad formats, the Ad Display SWF has an XML specification, which looks like this:

<adSwf version="1" trackStartURLs="http://trackingurl">
  <adSwfURL>http://path-to-ad-swf.swf</adSwfURL>
  <optionalArg>arg value 1</optionalArg>
  <anotherArg>arg value 2</anotherArg>
</adSwf>

When the player receives an ad in this format, it retrieves and executes the SWF at the specified URL. The SWF can then make an additional call or calls for the ad content itself as well as handle all the rendering and user events.  An Ad Display SWF can be linear or non-linear, acting like a video ad or an overlay ad.  Special APIs are provided to have linear ads act similar to Brightcove's built-in video format.

To help you learn how to write Ad Display SWFs, you can download a zip file, AdSwfDevKit.zip, that includes the following resources:

• Example of an Ad Display SWF – ExampleAdSwf.as and Example.swf
• Example of an ad translator for an Ad Display SWF – ExampleTranslator.as and ExampleTranslator.swf
• Library file for use when developing your ad Display SWF – bc_ads.swc
• API guide – an API reference for the AdSwf, AdSwfConfig, AdSwfContext, and AdSwfMediaEvent classes.

To learn about creating and using Ad Display SWFs, set up the example and see how it works. The main steps in setting up the example are:

1. Compile and host the example Ad Translator.
2. Compile and host the example Ad Display SWF.
3. Set up a player to use the example Ad Translator.
4. Add a key/value pair to the player to trigger a request that will deliver the example Ad Display SWF.
5. Load the player and see the ad play.

Setting up the Ad Translator

We provide an Ad Translator in the AdSwfDevKit.zip example zip so that you can easily try out the example ad SWF. You do not have to use the example Ad Translator. Instead of using the Ad Translator, you could just traffick the example Ad Display SWF as you would any other ad on your ad server. The Ad Translator, however, allows you to see the Ad Display SWF in the example without trafficking it on your ad server.

To set up the Ad Translator, you can either compile ExampleTranslator.as or just use the already-compiled ExampleTranslator.swf. To start with ExampleAdSwf.as:

1. Get bc_ads.swc and ExampleTranslator.as from AdSwfDevKit.zip.  Create a project in your development environment with ExampleTranslator.as as the main class.
2. Add bc_ads.swc as an external library. Make sure that you add it as an external library, rather than putting it in the library path. Otherwise, your SWF will be slightly larger than it needs to me.  If you are using Adobe Flex Builder, you can add it as an external library in the "Additional Compiler Options" by adding -external-library-path=../bc_ads.swc . If you are using Adobe Flash, you can simply drop bc_ads.swc into the same directory as your application .fla before you compile.
3. Compile ExampleTranslator.as and put the resulting SWF on a web server where your players can access it. We'll use this SWF later.

To use the already-compiled ExampleTranslator.swf:

1. Get ExampleTranslator.swf from AdSwfDevKit.zip.
2. Put the SWF on a web server where your players can access it.

Setting up the example Ad SWF

The next step is to compile and host the example Ad Display SWF. You can either compile ExampleAdSwf.as or just use the already-compiled Example.swf. To start with ExampleAdSwf.as:

1. Get bc_ads.swc and ExampleAdSwf.as from AdSwfDevKit.zip. Copy these files to a different folder than the one used for the Ad Translator project.
2. Create a project in your development environment with ExampleAdSwf.as as the main class.
3. Add bc_ads.swc as an external library. Make sure that you add it as an external library, rather than putting it in the library path. Follow the same steps that were done for the ad translator above.
4. Compile ExampleAdSwf.as and put the resulting SWF on a web server where your players can access it.

To use the already-compiled Example.swf:

1. Get Example.swf from AdSwfDevKit.zip.
2. Put the SWF on a web server where your players can access it.

Trying out the Ad SWF

Now that we have compiled and hosted the Ad Translator SWF and Ad Display SWF, we can use these two elements together to traffick an Ad Display SWF:

1. In the Brightcove Studio Advertising module, select a player to which you want to traffick the Ad Display SWF and click Edit.
2. In the Edit dialog for the player, select Override default Ad Translator URL and enter the URL of your example Ad Translator SWF.
3. Within the player load key/value pairs for the same player, add a new key/value of adSwf=http://host/adSwf.swf, changing the URL to the real location of your Ad Display SWF.
4. Click Save Changes.
5. Load the player in a browser. You should be able to load the player in a browser and see the example Ad Display SWF.

Creating your own Ad Display SWF

Now that you've seen how the Ad Display SWF works in the example, you should be able to see how to create your own Ad Display SWF. You can use the example, ExampleAdSwf.as, as a starting point. Your Ad Display SWF should follow the same basic structure. Review the comments in ExampleAdSwf.as to help you understand what is going on. As in ExampleAdSwf.as:

• Your Ad SWF class must extend com.brightcove.fl.advertising.adswf.AdSwf.
• Use Security.allowDomain("admin.brightcove.com") so that crossdomain.xml doesn't need to be set up for the SWF to communicate with the Brightcove player SWFs
• In the class constructor, you can add event hooks into the player or load anything else that would be needed for the ad SWF.  Often external SWFs are loaded from the constructor.
• Use configureAd() and configureComplete() to set up AdSwfConfig for the current ad.  If no settings need to be changed, these functions do not need to be used.  AdSwfConfig has a number of settings which should be looked through to determine if they need to be changed for your Ad Display SWF.
• AdSwfConfig.pauseVideoPlayer is a setting which has particular importance.  When set to true, the Ad Display SWF behaves as a linear ad.  This should be used instead of attempting to pause the video through the API, as it enables more features when used.  If pauseVideoPlayer is set to true, the AdSwfMediaEvent class can be used as well as the mediaDuration and mediaPosition APIs.  The AdSwfMediaEvent class allows the Ad Display SWF to respond to to pause, play, and volume events from the player.  The mediaDuration and mediaPosition APIs allow the Ad Display SWF to give duration information to the player for display.  Using all of these events and APIs when pauseVideoPlayer is set to true allows the Ad Display SWF to behave like a video ad.
• AdSwfConfig.keepVisibleAfterComplete should almost always be set to false, but it can be set to true for banner ads or other ads which should be displayed forever.  This setting should not be used to allow an Ad Display SWF to display multiple ads, as much of the functionality of the Ad Display SWF format will be bypassed if this is done.  Instead, mutliple ads should be displayed by having ad displayed through displayAd() with the policy being controlled external to the Ad Display SWF.
• You must override the displayAd() function. This is the function which displays the ad.   It will often load another SWF that is the actual ad. The function can change the state of the player or initialize the ad with AdSwfContext.  The player APIs can be accessed through AdSwfContext, which allows the Ad Display SWF to get information about different BEML components, change the ad display state through functions like showSponsorMessage(), get the size and location of the video player, and a lot more.
• The Ad Display SWF automatically enables the API for the player, so that even if you don't edit the player settings in the publishing module to enable APIs, the Ad Display SWF will still work.
• When the ad is done playing, call adComplete() to return control to the player.  Make sure to remove any event listeners that have been set up.