TechNote

An example of communication between JavaScript and Adobe Flash Player

What's Covered

• About ExternalInterface
• ExternalInterface example in ActionScript 2.0
• ExternalInterface example in ActionScript 3.0
• Defining JavaScript for ExternalInterface example (ActionScript 2.0 and 3.0)

This TechNote contains an example of communication between JavaScript and the Adobe Flash Player using the ExternalInterface class. You can download the source files (ActionScript 2.0 and ActionScript 3.0): externalinterface_files.zip

About ExternalInterface

The ExternalInterface class is the External API, an application programming interface that enables straightforward communication between ActionScript and the Flash Player container; for example, an HTML page with JavaScript, or a desktop application with Flash Player embedded.

Use of ExternalInterface is recommended for JavaScript-ActionScript communication over the use of fscommand(), CallFrame() and CallLabel().

From ActionScript, you can call any JavaScript function on the HTML page, passing any number of arguments of any data type, and receive a return value from the call.

From JavaScript on the HTML page, you can call an ActionScript function in Flash Player. The ActionScript function can return a value, and JavaScript receives it immediately as the return value of the call.

ExternalInterface is supported in the following combinations of browser and operating system:

Browser	Operating System
Internet Explorer 5.0 and later	Windows
Netscape 8.0 and later	Windows	Macintosh
Mozilla 1.7.5 and later	Windows	Macintosh
Firefox 1.0 and later	Windows	Macintosh
Safari 1.3 and later		Macintosh

ExternalInterface requires the user's web browser to support either ActiveX or the NPRuntime API that is exposed by some browsers for plugin scripting. See http://www.mozilla.org/projects/plugins/npruntime.html.

Note: For a complete matrix of which browsers support different features, see "A comprehensive list of supported Flash features, specific to each browser" (TechNote 14159). For SWF files targeting versions of Flash prior to Flash 8, you will need to use an alternative to ExternalInterface such as fscommand.

ExternalInterface example in ActionScript 2.0

This example demonstrates how to use ActionScript 2.0 and JavaScript to send a value from an HTML input text field to Flash, how to send text in Flash to HTML and how to get a return value from JavaScript after sending the text to HTML.

Creating the Flash file

1. Create a new ActionScript 2.0 Flash Document in Adobe Flash. Save the file with the file name: ExternalInterfaceExample.fla
2. Place 2 TextInput components on the stage and give instance names of: sending_ti and received_ti
3. Place a Button component on the stage next to sending_ti and give in instance name of: send_button
4. All of the code for the movie will be in Frame 1. Select the frame one of Layer 1 (or make a new layer for your ActionScript) and open the Actions Panel.
5. The code for this example will need to do things. First it will need to setup a callback for the Flash Object in HTML that JavaScript can use to invoke a function in ActionScript. This is done using ExternalInterface.addCallBack() which, in this example, will define a JavaScript function called sentTextToFlash that will call getTextFromJavaScript in ActionScript. The value passed into that function in JavaScript will be set to received_ti in getTextFromJavaScript. Secondly, the script will also define an event handler for the send_button instance to call a JavaScript function defined in the HTML using ExternalInterface.call() sending to it the text in sending_ti. The return value of ExternalInterface.call() is any value returned by that JavaScript call and will be defined in received_ti.
   This is the completed script:

    import flash.external.ExternalInterface; function getTextFromJavaScript(str:String):Void {  received_ti.text = "From JavaScript: " + str; } ExternalInterface.addCallback("sendTextToFlash", this, getTextFromJavaScript); function clickSend(eventObj:Object):Void {  var jsArgument:String = sending_ti.text;  var result:Object = ExternalInterface.call("getTextFromFlash", jsArgument);  received_ti.text = "Returned: " + result; } send_button.addEventListener("click", clickSend); 

6. Publish the SWF file with HTML.

Next you will need to define the HTML and JavaScript needed to interact with the SWF file.

ExternalInterface example in ActionScript 3.0

This example demonstrates how to use ActionScript 3.0 and JavaScript to send a value from an HTML input text field to Flash, how to send text in Flash to HTML and how to get a return value from JavaScript after sending the text to HTML.

Creating the Flash file

1. Create a new ActionScript 3.0 Flash Document in Adobe Flash. Save the file with the file name: ExternalInterfaceExample.fla
2. Place 2 TextInput components on the stage and give instance names of: sending_ti and received_ti
3. Place a Button component on the stage next to sending_ti and give in instance name of: send_button
4. All of the code for the movie will be in Frame 1. Select the frame one of Layer 1 (or make a new layer for your ActionScript) and open the Actions Panel (you may also decide to instead define these actions in a custom class).
5. The code for this example will need to do things. First it will need to setup a callback for the Flash Object in HTML that JavaScript can use to invoke a function in ActionScript. This is done using ExternalInterface.addCallBack() which, in this example, will define a JavaScript function called sentTextToFlash that will call getTextFromJavaScript in ActionScript. The value passed into that function in JavaScript will be set to received_ti in getTextFromJavaScript. Secondly, the script will also define an event handler for the send_button instance to call a JavaScript function defined in the HTML using ExternalInterface.call() sending to it the text in sending_ti. The return value of ExternalInterface.call() is any value returned by that JavaScript call and will be defined in received_ti.
   This is the completed script:

    import flash.external.ExternalInterface; import flash.events.Event; function getTextFromJavaScript(str:String):void {  received_ti.text = "From JavaScript: " + str; } ExternalInterface.addCallback("sendTextToFlash", getTextFromJavaScript); function clickSend(event:Event):void {  var jsArgument:String = sending_ti.text;  var result:Object = ExternalInterface.call("getTextFromFlash", jsArgument);  received_ti.text = "Returned: " + result; } send_button.addEventListener("click", clickSend); 

6. Publish the SWF file with HTML.

Next you will need to define the HTML and JavaScript needed to interact with the SWF.

Defining JavaScript for ExternalInterface example

1. Open the HTML created when having published the SWF for ExternalInterfaceExample.fla
2. Within the head tag of the HTML, create the JavaScript functions used to interact with the Flash movie. This consists primarily of two functions, one called formSend which will send text from an HTML form into Flash using the sendTextToFlash callback defined in ActionScript using ExternalInterface.addCallback, and another called getTextFromFlash which Flash can call using ExternalInterface.call. An additional function, getFlashMovie, is also created to help get a reference to the Flash movie object reliably simply using its name.
   This is the completed JavaScript placed in the HTML head:

    <script >  function getFlashMovie(movieName) {   var isIE = navigator.appName.indexOf("Microsoft") != -1;   return (isIE) ? window[movieName] : document[movieName];  }  function formSend() {   var text = document.htmlForm.sendField.value;   getFlashMovie("ExternalInterfaceExample").sendTextToFlash(text);     }    function getTextFromFlash(str) {   document.htmlForm.receivedField.value = "From Flash: " + str;   return str + " received";  } </script> 

3. Create the HTML form elements that will react with the Flash movie. For this example, this consists of two text field inputs and a send button, much like the setup in the Flash movie, placed below the Flash content. When the send button is clicked, the form is submitted calling formSend defined above.
   This is the completed form HTML:

    <form name="htmlForm" method="POST" action="javascript:formSend();">  Sending to ActionScript:<br />  <input type="text" name="sendField" value="" /><br />  <input type="submit" value="Send" /><br />  <br />  Received from ActionScript:<br />  <input type="text" name="receivedField"> </form> 

Open the HTML file in your browser and test communication between the JavaScript/HTML and the Flash SWF.

Note: If running the HTML from your hard drive, you will need to be sure that location is trusted, so that the interaction between Flash and JavaScript will correctly function. Otherwise, try uploading the HTML to a server and testing it remotely. For more information on security, visit the Flash Player Developer Center.

Search Support

---