breadcrumb arrow home | blog

ExternalInterface examples

Posted: 19/01/10

An image of ExternalInterface examples

ExternalInterface is the API in the Flash Player that allows you to send data into an embedded SWF once it's running in a web page. It also allows you to call functions in your web page from an embedded SWF.

There are 3 main players: the DOM (Document Object Model), the SWF, and the External Interface. The DOM is the web page, the SWF is your Flash application embedded in the page and the ExternalInterface is a 'go-between' that sits on the outside-edge of the Flash Player plug-in, permitting communication across the platform divide.

To call a method on or pass data into your SWF

In your application you need to register a method and a closure with the ExternalInterface object to allow the outer web page to call it.

Consider you have this code in an ActionScript class or a Flex application:

private function initialiseApp() :void

{

ExternalInterface.addCallback( "callMe", doSomething );

}

private function doSomething( text:String ) :void

{

trace( text );

}

Now in the web page in which you've embedded your application, you'll need to create some JavaScript that will obtain a reference to the SWF in the DOM, and then call the callMe method that you've registered with the ExternalInterface. Note that I've used SWFObject 2 to embed my SWF, and I'd always recommend the same.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>ExternalInterface Test</title>

<script src="swfobject2.js" type="text/javascript"></script>

<script type="text/javascript">

var flashvars = {};

var params = { allowscriptaccess: "always"};

swfobject.embedSWF("myApp.swf", "flashContent", "250", "250", "9.0.0", "", flashvars, params );

function handleClick()

{

document.getElementById( "flashContent" ).callMe( "This is text from the page" );

}

</script>

</head>

<body>

<div id="flashContent"></div>

<a href="#" onClick="handleClick();">Update text</a>

</body>

</html>

When the user clicks the Update text link on the page, the onClick JavaScript event is raised. This event is handled by the handleClick function, which in-turn calls the callMe function that was registered on the SWF ExternalInterface. The outcome is that you should see This is text from the page in the debugger console.

This code obtains a reference to the SWF from the DOM, allowing you to then call whichever functions you have registered on it.

document.getElementById( "flashContent" )

In the parameters of your Flash embed code, you need to ensure that the allowScriptAccess is set to "always" or "sameDomain". Failing to set this can mean that JavaScript/SWF communication is denied by the Flash Player (as a security feature).

var params = { allowscriptaccess: "always"};

swfobject.embedSWF("myApp.swf", "flashContent", "250", "250", "9.0.0", "", flashvars, params );

It is possible to register many functions with the ExternalInterface, and zero or more parameters can be passed through.

Call a function in the page or pass data to the page from a SWF

ExternalInterface can also work in the opposite direction, allowing you to pass data from an embedded SWF to the parent web page. The process is slightly easier, as there is no requirement to register methods with the ExternalInterface prior to use.

Consider that your Flash application code now looks like this:

private function initialiseApp() :void

{

ExternalInterface.call( "updateText", "Hello from the SWF" );

stage.addEventListener( MouseEvent.CLICK, onStageClick );

}

private function onStageClick( e:MouseEvent ) :void

{

ExternalInterface.call( "updateText", "The stage in the SWF was clicked" );

}

The initialiseApp method needs to be called as a result of an Event.ADDED_TO_STAGE or FlexEvent.CREATION_COMPLETE event, as you'll be attempting to add a listener directly to the stage.

The call method of the ExternalInterface object is used to call functions on the parent/outer web page. The call will happen whether or not these functions actually exist, and will fail silently in isolation, but may cause exceptions in your app if you're expecting a return value.

In the web page, the code has changed slightly to now be the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>ExternalInterface Test</title>

<script src="swfobject2.js" type="text/javascript"></script>

<script type="text/javascript">

var flashvars = {};

var params = { allowscriptaccess: "always"};

swfobject.embedSWF("myApp.swf", "flashContent", "250", "250", "9.0.0", "", flashvars, params );

function updateText( data )

{

document.getElementById( 'myText' ).innerHTML = document.getElementById( 'myText' ).innerHTML + "<br/>" + data;

}

</script>

</head>

<body>

<div id="flashContent"></div>

<div id="myText"></div>

</body>

</html>

Now when the stage is clicked in the SWF, the event handler calls updateText through the ExternalInterface, which in-turn appends the myText with the text passed from the SWF.

Read more about ExternalInterface in the Flash API documentation

Keywords for this post: externalinterface, javascript, actionscript 3, dom, page, html, addCallback, flash player