External API requirements and advantages

The external API is the portion of ActionScript that provides a mechanism for communication between ActionScript and code running in an "external application" that is acting as a container for Flash Player (commonly a web browser or stand-alone projector application). In ActionScript 3.0, the functionality of the external API is provided by the ExternalInterface class. In Flash Player versions prior to Flash Player 8, the fscommand() action was used to carry out communication with the container application. The ExternalInterface class is a replacement for fscommand(), and its use is recommended for all communication between JavaScript and ActionScript.

NOTE

If you need to use the old fscommand() function--for example, to maintain compatibility with older applications or to interact with a third-party SWF container application or the stand-alone Flash Player--it is still available as a package-level function in the flash.system package.

The ExternalInterface class is a subsystem that lets you easily communicate from ActionScript and Flash Player to JavaScript in an HTML page, or to any desktop application that includes an instance of Flash Player.

The ExternalInterface class is available only under the following conditions:

In all supported versions of Internet Explorer for Windows (5.0 and later)

In a container application such as a desktop application using an instance of the Flash Player ActiveX control

In any browser that supports the NPRuntime interface, which currently includes the following browsers:

Firefox 1.0 and later
Mozilla 1.7.5 and later
Netscape 8.0 and later
Safari 1.3 and later

In all other situations (such as running in a stand-alone player), the ExternalInterface.available property returns false.

From ActionScript, you can call a JavaScript function on the HTML page. The external API offers the following improved functionality compared with fscommand():

You can use any JavaScript function, not only the functions that you can use with the fscommand() function.

You can pass any number of arguments, with any names; you aren't limited to passing a command and a single string argument. This gives the external API much more flexibility than fscommand().

You can pass various data types (such as Boolean, Number, and String); you are no longer limited to String parameters.

You can receive the value of a call, and that value returns immediately to ActionScript (as the return value of the call you make).

WARNING

If the name given to the Flash Player instance in an HTML page (the object tag's id attribute) includes a hyphen (-) or other characters that are defined as operators in JavaScript (such as +, *, /, \, ., and so on), ExternalInterface calls from ActionScript will not work when the container web page is viewed in Internet Explorer.

In addition, if the HTML tags that define the Flash Player instance (the object and embed tags) are nested in an HTML form tag, ExternalInterface calls from ActionScript will not work.

Flash CS3

Comments

No screen name said on Aug 5, 2007 at 12:59 PM :

"In all other situations (such as running in a stand-alone player), the ExternalInterface.available property returns false."

Why is this? We would like to embed flash in a stand-alone player, but without ExternalInterface being available in is impossible for us to communicate with Flash.

Is there any way around this issue? I don't see why flash is unable to communicate out in this situation

oscarcs said on Aug 26, 2008 at 12:34 PM :

According to this:
"You can pass various data types (such as Boolean, Number, and String); you are no longer limited to String parameters. "

XML should be supported, right?

However, this is not working for me. As long, as I returned an object with a property being XML, the JavaScript function does not get call.

For example:
// MyClass has two types properties, name:String and localXML:XML

var testClass:MyClass= new MyClass();

testClass.name="test";
var myXML:XML = new XML();
myXML = <a>Test2</a>;
testClass.locaXML= new XML(myXML.toXMLString());
ExternalInterface.call("sayString",testClass);

If I set testClass.locaXML to null the Js function is called.

Thanks

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/9.0/main/00000339.html