Developing an Ad Rules SWF

Creating an Ad Rules 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 Rules SWF, please first contact your Account Manager to see if one of Brightcove's ad partners would work better for you.

Do you need to have more control over your ad delivery, even more control than you can get using the Brightcove Advertising module? If yes, then read on! This document introduces the Brightcove Ad Rules SWF feature, which you can use to customize the delivery time and the rendering of ads in players. The first half of this article describes your ad delivery options and the advantageous features of the Ad Rules SWF.  The second half offers technical instructions on how to create and use your Ad Rules SWF.

Ad policy options

There are several ways to set ad delivery timing for a Brightcove player. Let's review a few of the options available to Brightcove customers before we dive into the Ad Rules feature:

• Setting ad policy in the Advertising module. The most widely used option for controlling ad delivery is to set your ad policy via the Brightcove Studio's Advertising module. The policy you choose for your player persists in all player loads and allows for detailed ad delivery configuration. See Setting Ad Policies for more information.
• Setting ad policy with the Advertising API setAdPolicy. Another option is to set your ad policy via the Brightcove Advertising API setAdPolicy() method. This allows you to change or override ad policy settings dynamically. Almost all properties available in the Advertising module can be reset using adModuleInstance.setAdPolicy(). The changes made using setAdPolicy() persist only during a single player load and do not permanently change any of the settings exposed in the Advertising module. This allows you to customize when and how ads are delivered to their players but still lets you take advantage of the built-in Brightcove ad delivery logic (you can still use the Advertising module to edit policy values). This solution is usually the best choice if you need to change your ad policy at player runtime. This solution can even be used with syndicated players, as it can be packaged up into a module SWF via the Custom Plug-In feature in the Brightcove Studio Publishing module or directly in the player BEML. See Dynamically Setting an Ad Policy for more information.
• Setting ad policy with the Advertising API requestAd. Using the Advertising API requestAd()method allows you to make ad calls whenever you want. By using this method, you can force instant ad delivery in addition to whatever policy is set in the Advertising module. Or, you can choose to not set any ad insertion values in your player and use only requestAd() to deliver ads. This API can be very useful for ad delivery customizations. See Dynamically Making an Ad Request for more information.

Ad Rules SWF overview

All three of the solutions described above use the built-in Brightcove ad request and ad rendering capabilities. The Ad Rules SWF is an alternative solution that makes it much easier to integrate with third party ad libraries that control all aspects of advertising in Brightcove video players. The Brightcove Ad Rules feature provides a solution for the most complicated ad integrations by giving developers significant flexibility, while still allowing use of other key Brightcove features, like Ad Translators and Ad SWFs. With the Ad Rules SWF, you can create a complete custom ad integration and apply it to as many Brightcove players as you would like. Here's the basics of how the Ad Rules SWF works:

• The Ad Rules SWF is a Flash SWF file that a Brightcove player loads at runtime and that replaces the ad policy settings assigned in the Brightcove Studio Advertising module. Once you assign an Ad Rules SWF to a player, the ad policy settings in the Advertising module no longer apply and the default ad delivery logic of the player is overridden. All the assigned ad policy information is still accessible via the Advertising API, but the player recognizes only the Ad Rules SWF logic for ad delivery and display.
• Once you load the SWF, you have direct access to all the player APIs, as well as several Ad Rules methods that allow you to load Ad Translators, decide on whether to make an ad call at ad insertion points, and make an ad call via the loaded Ad Translator.
• The Ad Translator APIs allow you the option to use one of the built-in Ad Translators that Brightcove provides, including the default DFP implementation, or use an Ad Translator that's compiled in specifically for the Ad Rules SWF. You can also switch between different ad servers and ad networks, if needed, during a single player load.
• The ad insertion point APIs, which include APIs for onload, pre-roll, mid-roll, and post-roll ads, make sure that your ad gets shown in the player at the exact time that you specified. You aren't limited to these ad insertion points, however, as you can also play an ad at any other point that you need.
• The display of the ad can be handled many ways. You can use the built-in Brightcove ad formats if they work for your case. If you are integrating a third party ad library, you can put all your ad display logic in your Ad Rules SWF and use the Player API to change the state of the player during ad rendering. Or, you could use all three of the Brightcove Advertising developer features — Ad Rules (ad policy logic), Ad Translators (ad call and delivery manipulation), and Ad SWFs (ad display) — to create a seamless custom ad integration.
  
• You can use the Ad Rules SWF for an individual player or at the account level for all your players, including any virally distributed or syndicated players. Only one Ad Rules SWF can be set per player.

Several partners have already taken advantage of the Ad Rules SWF in order to integrate with Brightcove players. The Tremor Media video monetization platform, Acudeo, has been integrated with Brightcove players using the Ad Rules SWF feature. Brightcove also integrated Yahoo's newest digital advertising platform, APT, using the Ad Rules SWF. If you intend to use the Ad Rules SWF to integrate another third party ad library and delivery system, be sure to contact your Account Manager or Customer Support first to see if Brightcove already has plans to partner with that particular third party.

Ad Rules SWF Example

Now, let's walk through an example Ad Rules application. Before you begin, be sure to read over Developing Ad Translators and Developing Ad SWFs. It is helpful to thoroughly understand both Ad Translators and Ad SWFs (and what they are used for) before beginning work on an Ad Rules SWF. You'll want to carefully analyze how all the Brightcove features work together in Ad Rules SWFs since, for some integrations, one of the simpler Brightcove ad policy solutions listed above may be sufficient. For the more complex integration, however, using a flexible Ad Rules SWF is definitely the way to go.

To help you learn how to write an Ad Rules SWF, you can download a zip file, AdRulesDevKit.zip, that includes the following resources:

• Ad Rules example: ExampleAdRules.as and Example.swf (also, ExampleTranslatorWithAdSwf.as, ExampleAdSwfForAdRules.as, and FakeAd.as that are compiled into Example.swf)
• Ad Rules using DFP example: DFPExample.as, DFPExample.swf, and DFPExample_config.xml
• Library file: bc_ads.swc
• API guide: an API reference for the AdRules and AdRulesContext classes. These classes are also available in the Advertising API reference.

To learn about creating and using Ad Rules SWFs, set up the example and see how it works. Here are the main steps:

1. Compile and host the example Ad Rules SWF.
2. Set up a player to try out the example Ad Rules SWF. Load the player and see the ad render.
3. Create your own Ad Rules SWF.
4. Use the DFP Ad Translator in your Ad Rules SWF.

Compiling and Hosting the Example Ad Rules SWF

To try out the example Ad Rules SWF, you can either compile ExampleAdRules.as or just use the already-compiled Example.swf. To start with ExampleAdRules.as:

1. Get bc_ads.swc and ExampleAdRules.as, ExampleTranslatorWithAdSwf.as, ExampleAdSwfForAdRules.as, and FakeAd.as from AdRulesDevKit.zip.
2. Create a project in your development environment with ExampleAdRules.as as the main class. If you are using Adobe Flash, set ExampleAdRules as your Document Class in a .fla file.
3. Add bc_ads.swc as an external library. Make sure that you add it as an external library to prevent compiling in unnecessary classes. For example, 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.
4. Compile ExampleAdRules.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 AdRulesDevKit.zip.
2. Put the SWF on a web server where your players can access it.

Trying Out the Example Ad Rules SWF

Now that we have compiled and hosted the Ad Rules SWF, we can use it to override an ad policy in a player.

1. Talk with your Account Manager about getting your account enabled for custom Ad Policy SWFs.
2. Once your account has been enabled, go to the Brightcove Studio Advertising module, select a player that you want to apply the example Ad Rules SWF to, and click Edit.
3. In the Edit dialog for the player, click the Ad Source drop-down and select Custom Ad Rules SWF URL.
4. Enter the URL of your hosted example Ad Rules SWF (for example, http://host/Example.swf) and click Save Changes.
5. Load the player in the browser. The example Ad Rules SWF simulates a pre-roll and post-roll ad policy, so you must click a video in order to see the example ad. The example ad will appear as a smiley face in the video window, the content will be paused, and the player controls will only show 'Sponsor Message.' This ad simulates a linear ad that does not allow user interaction.

Cross-domain security settings

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 Rules SWF. If your Ad Rules SWF is hosted on http://example.com, include this line in your crossdomain.xml file:

<allow-access-from domain="example.com" />

You could also choose to add Security.allowDomain("admin.brightcove.com"); to your main Ad Rules SWF.

Creating Your Own Ad Rules SWF

Let's use ExampleAdRules.as as a starting point for understanding how the Ad Rules SWF works. The example SWF uses an ad translator to load an ad SWF which renders a pre-roll ad every time a video is played. Very little code is necessary for both ExampleAdRules.as and ExampleTranslatorWithAdSwf.as — most of the ad serving logic is in ExampleAdSwfForAdRules.as. You could choose to bypass the ad translator route and put all ad serving logic in the main Ad Rules class itself, but the Ad SWF framework allows you to integrate directly with Brightcove players, which makes development much easier. For example, you can set configuration properties in ad SWFs that will allow the player to re-size the ad automatically for you in full screen or pause the video player when the ad renders. The comments in all three classes should help you understand what is going on.

Let's walk through several of the key components of the example Ad Rules SWF:

• Your Ad Rules SWF must extend com.brightcove.fl.advertising.adrules.AdRules.

• You must override the setAdRulesContext() function as it lets you know when the AdRulesContext object is ready to be used. You can use the AdRulesContext object to load the player API and use it in your AdRules class. If you want to load the player API here the function will look something like this:

override public function setAdRulesContext(adContext:AdRulesContext):void {  
    this.adContext = adContext;
  
    // before we do anything else, we load the API modules for potential use  
    adContext.moduleLoader.addEventListener(Event.COMPLETE, modulesLoaded);  
    adContext.moduleLoader.loadModules();
}

In the example, we wait to load the player API until after our ad translator is ready. So, we use two more functions in AdRules - setAdTranslator() and adTranslatorLoaded(). The ad translator is compiled in in setAdRulesContext() so that the translator is immediately initialized. You could also load the translator if it is hosted somewhere else by using loadAdTranslator(). If you choose to set or load an ad translator you must override the adTranslatorLoaded() function as this function is triggered once the translator is finished loading and is ready for interaction.

We also initialize our ad SWF in setAdRulesContext() and pass that instance to our ad translator. This allows us to have access to the Ad SWF instance in the Ad Rules SWF but still handle all the ad display logic in the Ad SWF. Once the Player API has been loaded and is ready to be used (see 'modulesLoaded' below), then we pass the Ad API reference to the Ad SWF so that the API doesn't have to be loaded or accessed again. This just cuts down on code duplication between the different ad tools. In this example, after you have access to the player API, your Ad Rules SWF is ready to be used by the player. At this point, you must call adRulesReady(), as shown below, to tell the player that the Ad Rules SWF is ready for interaction. If you forget, or just fail to call, this function, your player will hang, since it hasn't been told by the Ad Rules SWF to move on.

/**
* Set the ad rules context object.
*/
override public function setAdRulesContext(pAdRulesContext:AdRulesContext):void {
    context = pAdRulesContext;             

    // Set the ExampleTranslatorWithAdSwf translator as current translator by compiling it in.
    // Pass the ad SWF reference to the ad translator for display.
    exampleAdSwf = new ExampleAdSwfForAdRules();
    setAdTranslator(new ExampleTranslatorWithAdSwf(exampleAdSwf));

    // Instead of setting the translator directly, you could also call            
    // loadAdTranslator() here to load the translator from a URL.            
    // adTranslatorLoaded() will still be fired once the translator is            
    // loaded and ready for interaction.            
    // loadAdTranslator("http://example.com/adtranslator.swf");        
}       

/**
* Override the handler in AdRules that indicates whether or
* not the translator has finished loading. Load the player API
* modules now.
*/
override public function adTranslatorLoaded():void {
    adContext.moduleLoader.addEventListener(Event.COMPLETE, modulesLoaded);  
    adContext.moduleLoader.loadModules();      
}

/**
* Called when the API modules have been loaded.
*/
private function modulesLoaded(pEvent:Event):void {
    context.moduleLoader.removeEventListener(Event.COMPLETE, modulesLoaded);

    // now that the APIs are loaded in we can get the modules
    adAPI = context.moduleLoader.getModule("advertising");
    // pass the advertising API module to the ad SWF so the API doesn't have to
    // be loaded every time an ad call is made.
    exampleAdSwf.adAPI = adAPI;

    // adRulesReady() MUST be called at some point in your ad SWF
    // or the player will hang. Calling this function tells the player
    // that the ad rules SWF is ready. In this simple case, we wanted to make sure
    // all our API modules were loaded and ready to be used before we tell the
    // player that our SWF is ready.
    adRulesReady();
}

You can also set up ad insertions in the ad rules SWF. In this example, we always want to show a pre-roll ad before the video content starts playing back as well as a post-roll ad once the video content is done playing. We make use of the ad insertion API which is documented in AdRules.

All we need to do is override both the prerollCheck() and postrollCheck() methods in AdRules. Then, we call callAdTranslator() to trigger the ad request and we call prerollCheckComplete() to let the player know that we are done checking for that particular insertion point. Using these APIs allows you to get and display an ad exactly when you want so any timing issues can be avoided. Other APIs like midrollCheck(), midrollCheckComplete(), onLoadCheck(), and onLoadCheckComplete() are also available by extending AdRules. See ExampleAdRules.as to view an example of how to use the mid-roll insertion API and DFPExample.as to view an example of using the onload insertion API.

/**
* Override the AdRules method. This is called whenever a pre-roll
* ad can be played. For this example, we want to play both pre-rolls and
* post-rolls on every video so execute 'callAdTranslator' here to play an
* ad at the pre-roll insertion, right before the content starts to play
* back.
*/
override public function prerollCheck():void {
    // callAdTranslator triggers "fetchAd" in ExampleTranslatorWithAdSwf.as
    callAdTranslator();
    // Let the player know that we are done checking for a pre-roll ad.
    // See AdRules doc for more information.
    prerollCheckComplete();
}

/**
* Override the AdRules method. This is called whenever a post-roll
* ad can be played. For this example, we want to play both pre-rolls and
* post-rolls on every video so execute 'callAdTranslator' here to play an
* ad at the post-roll insertion, right after the content finishes playing.
*/
override public function postrollCheck():void {
    // callAdTranslator triggers "fetchAd" in ExampleTranslatorWithAdSwf.as
    callAdTranslator();
    // Let the player know that we are done checking for a post-roll ad.
    // See AdRules doc for more information.
    postrollCheckComplete();
}

In ExampleTranslatorWithAdSwf.as, the translator tells the player to use the Ad SWF (the one we already initialized in our ad rules class) to render all ads in the player using the function useAdSwf() in the required function override fetchAd(). See the translator class comments for more details and explanation. Basically, this ad translator tells the player to always use the specified Ad SWF to display ads.

If you open up ExampleAdSwfForAdRules.as, you'll see that we override config.pauseVideoPlayer in the class constructor and set it to true. We do this because we want to simulate a linear ad by pausing content playback while the ad renders. Setting this config to true tells the player to act as though this ad is a linear ad.

public function ExampleAdSwfForAdRules():void {   
    config.pauseVideoPlayer = true;
}

Also, in ad SWFs, we must override the function displayAd(), as fetchAd() in the translator triggers this function. In ExampleAdSwfForAdRules.as, the ad is rendered when displayAd() is called and we use the advertising API reference to call showSponsorMessage(true) so that the player controls will be disabled during our ad play. Alternatively, you could choose to use allowThirdPartyControl(true) instead of showSponsorMessage(true) if you want to allow the user to be able to interact with your ad via the volume control and play/pause control. You can see descriptions of these various ad modes in the AdvertisingModule API documentation. In ad SWFs, you must also remember to override adComplete() and remove references as needed before the ad play is complete. See the ad SWF class for more details and explanation.

In summary, the basic workflow for a player using the example Ad Rules SWF is the following:

1. Player begins loading.
2. The ad rules SWF is loaded.
3. The example ad translator and ad SWF classes are initialized (see ExampleAdRules.setAdRulesContext()).
4. Once the player API modules are loaded, an advertising API reference is passed to the ad SWF (see ExampleAdRules.modulesLoaded()).
5. The player finishes loading.
6. User clicks "Play" to start playing the first video.
7. ExampleAdRules.prerollCheck() is triggered before the content starts playing back. ExampleTranslatorWithAdSWF.fetchAd() is called which, in turn, calls ExampleAdSWFForAdRules.displayAd().
8. Once the ad SWF has displayed for 6 seconds (see ExampleAdSwfForAdRules.showAd()) ExampleAdSwfForAdRules.adComplete() is triggered, telling the player that the ad is finished playing back.
9. The video begins to play. Two mid-rolls are triggered (ExampleAdRules.midrollCheck()), one at six seconds and one at 12 seconds. Step #8 follows both mid-roll calls.
10. Once you reach the end of the video, ExampleAdRules.postrollCheck() is triggered and step #8 (ad display logic in the ad SWF) follows.

Using the DFP Translator with Ad Rules SWFs

There may be cases where you need to use the default Brightcove ad translator for DFP. This translator is compiled into the players, so you cannot load it in using loadAdTranslator(). If you need to set it as the current ad translator, however, you can use the function useDefaultDFPTranslator(true) in AdRules. Then, you can use the Player API to set the ad server URL on the player ad policy (AdvertisingModule.setAdPolicy(adPolicyObject)). See DFPExample.as and DFPExample_config.xml in AdRulesDevKit.zip for an example of this.