Passing Config Values to a Player Embedded in a Flash Shell

The Brightcove Player allows you to set "startup" values in the snippet that will override what you've programmed in the console. You can set boolean (True/False) values like autoPlay or instruct the player to load a particular title or lineup. For more details on what you can and can't do, see this Help article: Customizing Player Behavior In a Page.

Many publishers will dynamically generate the pages that Brightcove players live on and these startup values along with them. If your Brightcove Player is embedded directly on the page using the JavaScript publishing code, you can simply have the pages generated with the values in the appropriate locations in the snippet. However, if you're embedding the Brightcove Player inside a custom Flash shell, you'll need to write some JavaScript and ActionScript code to pass these values to the snippet inside - it won't happen automatically.

This How-To will show you an example of passing a titleID and an autoPlay parameter to a Single Title Player inside a Flash shell.

Before you begin

Presumably, you're already familiar with embedding a Brightcove Player in a Flash shell. If not, read this How-To.

This example also requires knowledge of ActionScript 2.0 for Flash Player 8, specifically we will be using the ExternalInterface API to transfer data between ActionScript and JavaScript. If you are using a version 1.0 template for Flash Player 7 compatibility, you can use these principles to do the same with the FSCommand or setValue APIs, however we won't cover that in a How-To. We'll also be using the "Object.watch()" function.

You can download the sample files here. Note that you need to provide your own playerId and titleId before the sample will work.

Prepare the snippet

We first want to configure our Flash shell and the snippet to accept new values before creating the Brightcove player. To do this, we'll need to make a few changes in the snippet. Begin by placing the snippet in your Flash movie on Frame 1 of a new layer on the main timeline. (If you choose to use a different location some of your other code may need to be changed to match.)

We're working with a Single Title Player, and we'll be passing in new values for config["videoId"] and config["autoStart"]. We need to delay the creation of the player - we don't want the player to be created until the variables contain our new values. To do this, we prevent the snippet from calling the "createPlayer" function by commenting it out like so:

// createPlayer(config);

The snippet is now prepared - when we're ready to create the player we can call createPlayer() ourselves. Let's move on to write the code that will do that.

Write the AS-JS bridge code

The actual transfer of the data from the HTML page, in JavaScript, to our Flash shell, in ActionScript, will be done by using the ExternalInterface API. This API was added to the Flash Player and to ActionScript in Flash Player 8 to make this cross-container communication easier. Despite its programmer-y name, it's remarkably easy to use. The important thing to keep in mind when using it to talk to an HTML page is that the Flash shell will ususally take slightly longer to load than the HTML page. Therefore, it's wise to begin the communication from ActionScript when the shell is ready.

ExternalInterface is great because it will allow us to call into JavaScript and expect a return value of any type. We simply specify the function to call and then handle the result. Because we're interested in passing two values, it will be most convenient to wrap them in an object.

Create a new layer, below the layer on which you placed the snippet, and add the following code on Frame 1:

init = flash.external.ExternalInterface.call("getConfigValues");

This is our call to the page and "init" is the result - it's that simple.Now to handle the result, we set the values for our config properties to the corresponding values in "init", and then call createPlayer() to instantiate the player.

config["autoStart"] = init["autoStart"];
config["videoId"] = init["videoId"];
createPlayer(config);

It's important that this code execute after the snippet code has run, which is why this layer is below the snippet layer on the timeline - Flash Player executes layers from top to bottom.

We're all set in Flash, now let's move on to the HTML.

Write the JavaScript code

Now we need a basic HTML page in which to embed our shell. You can use whatever method of embedding you like, as long as you keep in mind the two primary requirements of embedding a Brightcove Player on a page (even if it's in a shell):

1. Make sure the name/id attributes of Flash object match what is specified for config["flashId"] in the snippet.
2. Make sure that both allowScriptAccess attributes are set to "true".

In the HEAD section of your page, insert a script block. In this block we'll define the function that Flash is going to call to retrieve the values:

function getConfigValues() {
	var init = new Object();
	init["videoId"] = 123456789;
	init["autoStart"] = true;	
	return init;
}

This function simply creates an object called "init", populates it with the values we want and returns it. Flash Player takes care of marshalling the data types to Flash behind-the-scenes. All you need to know as a programmer is that the same object comes out on the other end in Flash! And that's it - preview your work and you'll see the player load the title you've specified in the HTML. It will also start playing right away!

Extending this example

This is all the code that's required to broker the transfer. This code can easily get more complicated depending on your scenario, but once you get this simple scenario working you will have the mental model necessary to adapt it to your specific needs.

If your page is going to be dynamically generated, you can code your server-side code to place the values in the right place in the JavaScript. There are many other ways to do it as well - as long as the values exist as valid JavaScript variables they will be accessible from both JavaScript and Flash.