Using getStage to Access Player Configuration Parameters

The Brightcove 3.2 release added to the Player API's Experience module a method named getStage() that returns a reference to the Stage. This allows for numerous possibilities, including the ability to extract parameters passed in the player publishing code such as publisherID or @videoPlayer and even custom values you include yourself. Passing custom values in the player publishing code could be extremely valuable when integrating with analytics systems and numerous other possible integrations. This functionality could be used by a container SWF containing a Brightcove player, an embedded component SWF, and even the JavaScript based APIs. This example show how to use this functionality inside a component SWF, as this is likely the most beneficial integration.

Click here to see this functionality in action.

Download a zip file that contains the ActionScript project files for this example.

If you are not familiar with component SWFs, you should reference Creating Custom Player Components in the Brightcove help topics. This example requires the use of the Player API SWC.

Creating the Component SWF

Component SWFs are written in ActionScript 3 and can be created in any IDE capable of creating SWFs. When using the Player API SWF to create a module, you should have your SWF's document class extend the CustomModule class included in the SWC. When the player is fully initialized it will execute the SWF's initialize() method. This method will grab a reference to the player's Experience module and use that module's getStage() method to access the flashvar configuration parameters included in the player publishing code. This example simply traces those values but you could use them in a number of different ways.

/** 
 * Called after TEMPLATE_READY by super class.  
 */ 
 override protected function initialize():void {
        trace("[SWF] " + "initialize()");
        
     	exp = player.getModule(APIModules.EXPERIENCE) as ExperienceModule;
        
        var parameters:Object = exp.getStage().loaderInfo.parameters;
        
        trace("[SWF] videoId: " + parameters["@videoPlayer"]);
        trace("[SWF] bgcolor: " + parameters.bgcolor);
        trace("[SWF] width: " + parameters.width + " height: " + parameters.height); 
        trace("[SWF] playerID " + parameters.playerID);
        trace("[SWF] publisherID: " + parameters.publisherID); 	
        trace("[SWF] myCustomValue: " + parameters.myCustomValue); 
}

Including your Component SWF in a player

Now that you have created your component SWF, you need to:

• publish it on a public web server,
• ensure a proper crossdomain.xml file is on the web server to allow the SWF to be loaded, and
• tell the player to load the SWF. This can be done by adding the component SWF into the player template using a SWFLoader or Module element in your BEML player template. It can also be done in the Publishing module by editing the player and selecting the Analytics tab. In the Analytics tab, you can enter the URL of one SWF to be loaded into the player at run time.

This player will now request the custom SWF at run time and execute the logic you've coded into the SWF.

Development Tip

Developing component SWFs can be complicated by the fact that trace() statements are visible only in an IDE, but a component SWF is going to be run only inside of a Brightcove player. To get around this limitation, you can by using the Flash debug player along with the flashlog.txt file described in this article.

Alternatively, I prefer to use the call() method of ExternalInterface. This allows you to call JavaScript on the page where you publish the player that contains your component SWF. As an example, this would call JavaScript and open an alert window containing the words "Called from component SWF":

ExternalInterface.call("alert","Called from component SWF");