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 Video Cloud customer and think your project or product calls for use of the Video Cloud Ad Display SWF, please first contact your Account Manager to see if one of the Video Cloud ad partners would work better for you.

This document describes how to create an Ad Display SWF. By default, a Video Cloud 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 and render a unique Ad Format in your Video Cloud player, that is not one of Video Cloud 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 can make linear ads act similar to the Video Cloud built-in video format.

To help you learn how to write Ad Display SWFs, you can download a zip file, AdSDK.zip, that includes (under the adswf directory) 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 AdSDK.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 from AdSDK.zip and ExampleTranslator.as from the asdwf/example directory in AdSDK.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 be. 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 the asdwf/example directory in AdSDK.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 from AdSDK.zip and ExampleAdSwf.as from the asdwf/example directory in AdSDK.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.

Note: You need to make a few changes in your project setup to use both bc_ads.swc and BrightcovePlayerAPI.swc in your Ad Display SWF. Add both bc_ads.swc and BrightcovePlayerAPI.swc as regular libraries if you are using Adobe Flex Builder. You can do this through your project's properties (Library path tab) or in the Additional Compiler Options by adding -library-path=../bc_ads.swc. Also, note line 138 in ExampleAdSwf.as where the AdSwfContext.moduleLoader must be wrapped in com.brightcove.fl.advertising.api.BrightcoveModuleWrapper to be used with both development swcs (ie: moduleLoader = new BrightcoveModuleWrapper(adContext.moduleLoader as IEventDispatcher)). After adding both development swcs and wrapping your moduleLoader, you should be able to type all variables and use the swcs to the fullest.

To use the already-compiled Example.swf:

1. Get Example.swf from the asdwf/example directory in AdSDK.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 Video Cloud 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 Custom Ad Translator SWF URL from Ad Source drop-down list.
3. Within the player-load key/value pairs for the same player, add a new key/value pair of adSwf=http://host/adSwf.swf, changing the URL to the actual 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:

1. Your Ad SWF class must extend com.brightcove.fl.advertising.adswf.AdSwf.
2. Use Security.allowDomain("admin.brightcove.com") so that you don't need to set up a crossdomain.xml security file to allow the SWF to communicate with the Video Cloud player SWFs.
3. 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.
4. Use configureAd() and configureComplete() to set up AdSwfConfig for the current ad.  If no settings in AdSwfConfig 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, since 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.

5. 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.
6. 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.
7. When the ad has finished playing, call adComplete() to return control to the player.  Make sure to remove any event listeners that have been set up.