Let's begin with a succinct definition of what we are about to do:

"In AS Script Injection, complete and unmodified JavaScript and/or VBScripts are stored inside AS3 files using XML, and are then parsed and sent to the browser, typically using the ExternalInterface class."

That's all there is to it. Of course, getting it all to actually work is the trick, and that's what this tutorial is all about.

Before we dive in, however, we must first dispel some common misconceptions about the ExternalInterface class:

  1. Flash's ExternalInterface can only call named functions.
  2. Called functions must already be on the webpage in <SCRIPT> tags.
  3. ExternalInterface only works with global functions.
  4. In browsers, ExternalInterface only works with JavaScript .

None of these are true, as we shall soon see:

False: Flash's ExternalInterface can only use named functions, and they must already be on the webpage inside <SCRIPT> tags.

Nothing could be further from the truth! ExternalInterface works by taking your supplied string and performing a JavaScript eval() on it, forcing the browser to see the string as a JavaScript function of the same name (if one exists). It then executes a call() on that function, adding any arguments you supplied.

The first key to script injection is that initial eval() statement; JavaScript 's eval function is far more powerful than ActionScript's, and will attempt to turn literally any string passed to it into a proper value, object or function. The only problem is that eval() only interprets a single entity (i.e. a single var, object, or function name) … send it two or more of these entities and it crashes.

This leads us to the second key element: the fact that JavaScript, like ActionScript, can "wrap" almost any number of individual entities within a single anonymous function. The eval() will see only this "Wrapper Function" (a single entity), but will happily interpret everything inside of it. That's dolomite baby!

Because of this, ExternalInterface can not only interact with unnamed functions, it can send them, execute them, and even get a result from them. Consider the following examples. We'll start with the "traditional" use of ExternalInterface, and build our way up to an Injected Script complete with Wrapper Function.

Traditionally, ExternalInterface takes a single string to be evaluated as a function name, and any number of optional arguments (primitives or simple objects), as shown below:

ExternalInterface.call("alert", "foo")

This "normal" form of ExternalInterface executes the JavaScript "alert()" function from Flash, and will display "foo" as the alert-text. But you can also write it like this, and it will function the exact same way:

ExternalInterface.call("alert('foo')")

The function is still executed because Flash converts the entire command into a string, sends it to the browser, then performs a JavaScript eval() on the string. The eval() recognizes this as a function, and executes it. Lucky for us, this also works with unnamed functions, so

ExternalInterface.call("function(){}")

is perfectly valid; the anonymous function will actually get executed in the global namespace once it hits the browser. Which means that this…

ExternalInterface.call("function(){alert('foo');}")

…is an equally valid way to write ExternalInterface.call("alert", "foo"), since the anonymous function will get called, and will, in turn, call our alert function. But it gets better! Knowing this trick, there's no reason we can't tuck TWO alerts inside that anonymous function:

ExternalInterface.call("function(){alert('foo'); alert('bar');}")

...which will trigger both alerts, one after the other. In fact, you can embed just about any series of JavaScript commands, functions, variable declarations etc inside a single anonymous function and it will execute, as this more complex example shows:

var js:String = "function(){function myFunc(str){alert(str);};myFunc(Foobar);}";
ExternalInterface.call(js)

Because that example was packed as a single-line string, it's a little hard to read, so I'll explain. When fired off by call(), we first execute our anonymous wrapper function, which creates a local function called myFunc() (technically a "method" since it resides within another function), which, when called, shows another alert box, then finally executes myFunc(). Simple code: powerful implications! Here's that JavaScript again, written out normally so you can read it:

function(){
    function myFunc(str){
        alert(str);
    };
    myFunc('foo');
}

Of course, in order to actually work, all that JavaScript needs to be formatted as a string, which means we either write it out as a ridiculously long string as above, or we use concatenation and escaping as shown below...

var js:String = "function(){"
js+="function myFunc(str){"
js+="alert(str);};"
js+="myFunc(Foobar);}";
ExternalInterface.call(js)

...which is almost as annoying and confusing. Wouldn't it be nice to be able to write that code out directly inside Flash, as pure JavaScript, and not have to bother about string conversions?