But there's an annoying thing with that. You need to load up that remote swf and then access it like a dynamic object. No compiler-time type checking. Not the standard event mechanism. And no code-completion from within Flex Builder.
Luckily for you, I went through and made a wrapper class that you can download from here:
This will handle the loading of the remote swf, dispatching events when it loads (or fails to load) and then wraps the API for the entire process. There's nothing revolutionary in there, it's mostly takendirectly from that livedocs page above.
So now that you have that handy-dandy wrapper class, lets look at how to actually get something done.
First thing, go into your AIR application's -app.xml file and make sure allowBrowserInvocation is set to true. By default it's set to false.
<allowBrowserInvocation>true</allowBrowserInvocation>
If you don't do this, you won't even be able to query version information on your application. But, be careful. By doing this you're letting any website launch your AIR application from a web page. You need to be careful in how much your app trusts command line arguments passed to it. For instance, you should never pass a file to delete on the command line.
Now that you've set allowBrowserInvocation to true, create a new .air file and post that to your website somewhere.
Using the wrapper class to interact with your application
Either open an existing Flex or Actionscript project in FlexBuilder and put the source to the AIRBrowserRuntime.as somewhere that the compiler will find it. Somewhere in your main application, create an AIRBrowserRuntime object, set some event listeners, and call the load() method to load the air.swf file from Adobe's servers.
var api:AIRBrowserRuntime;
...
api = new AIRBrowserRuntime();
api.addEventListener(AIRBrowserRuntimeEvent.READY, onReady );
// Optional: api.addEventListener(IOErrorEvent.IO_ERROR, onAirFail );
api.load();
Once the READY event is dispatched, you can start calling methods to query application versions, install apps, or launch applications.
Checking if AIR is installed
To see if the AIR runtime is installed, call the getStatus() method. It will return one of three values.
available - The AIR runtime can be installed on this computer but currently it is not installed
unavailable - The AIR runtime cannot be installed on this computer.
installed - The AIR runtime is installed on this computer.
Example:
switch( api.getStatus() )
{
case "available": trace("AIR is available, but not installed."); break;
case "unavailable": trace("AIR is not available for this computer."); break;
case "installed": trace("AIR is already installed on this computer."); break;
}
Checking the version of an installed application
The getApplicationVersion method will check to see if a given application is installed and give you the version if it is. This method operates asynchronously so you have to create an event listener before you call it. If you look at the method signature...
public function getApplicationVersion(applicationID:String, publisherID:String) : void
You'll see that it takes an applicationID and a publisherID. The applicationID is just value of the <id> tag of your application descriptor (the -app.xml file). It'll probably be something like this, but you need to make sure to make each application unique:
<id>com.agileagenda.AgileTracker</id>
The publisherID is a little trickier to find. That doesn't get assigned until you actually sign your .AIR file with your code-signing key. I know of 2 ways of finding it, but there's probably an easier way (please leave a comment if you know how).
Warning about Publisher ID: If you change the key your sign your app with, the publisher ID will change.
Option 1: Get it at runtime.
In your application's main MXML throw up an Alert message with the publisher ID. Then build a .air, install the .air and run it. Copy & Paste the result. Example:
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="init()" >
<mx:Script>
<![CDATA[
protected function init() : void
{
Alert.show( nativeApplication.publisherID);
}
]]>
</mx:Script>
</mx:WindowedApplication>
Which results in something resembling:
It's hard to see in that picture, but the publisher ID is: F49A4D8DF78A1FEE7A3BE440DC11BAB18D922274.1 as it wraps to two lines.
Option 2: Get it after install
This is probably a bit easier, but I'm not 100% sure where this directory goes on a windows box.
On OSX (maybe on Windows, I'm not sure exactly where) the application storage directory that gets created for your application has the publisher ID appended to it. So if you look in your user directory -> Library -> Preferences, you should see a directory that starts with your application ID and ends with your publisher ID.
As you can see there, we get the same publisher ID value as Option #1.
On to checking installed version
Now that you have your application ID and your publisher ID you can make a call from your web application to the API to request the installed version of your AIR application. This operates asynchronously so you'll need an event listener for the result.
Example:
api.addEventListener(AIRBrowserRuntimeEvent.APP_VERSION_RESULT, onTrackerVersionResult );
api.getApplicationVersion( "com.agileagenda.AgileTracker", "F49A4D8DF78A1FEE7A3BE440DC11BAB18D922274.1" );
...
protected function onTrackerVersionResult(event:AIRBrowserRuntimeEvent) : void
{
trace("Tracker version installed: " + event.detectedVersion );
}
The event.detectedVersion that comes back will be the value in your application descriptor version tag. Mine looks like this:
<version>v1</version>
So the trace output looks like this:
Tracker version installed: v1
Launching an installed AIR application
Assuming you followed along in the previous section, you have an Application ID and a Publisher ID ready. To launch an AIR app from a web app you just call
api.launchApplication( "com.agileagenda.AgileTracker", "F49A4D8DF78A1FEE7A3BE440DC11BAB18D922274.1" );
launchApplication has a third, optional, parameter called arguments and is typed as an array. Anything you pass into that will be passed along to the application in an INVOKE event. This way you can pass information from the web application to the AIR application. Example:
api.launchApplication( "com.agileagenda.AgileTracker", "F49A4D8DF78A1FEE7A3BE440DC11BAB18D922274.1", ["Argument1","Argument2" ] );
Be careful, the arguments are very restrictive in what characters can be passed. Things like dashes, percent signs, underscores, all cause a runtime exception on the web application. You're probably safest only using alphanumeric characters. I haven't found a comprehensive list of what characters are or are not valid. If someone has that, please leave a comment below. This was done for security reasons.
Installing an AIR application
To install an AIR application, all you need to do is call the installApplication with the absolute URL to the .air file you want to install. Example:
api.installApplication("http://www.agileagenda.com/download/AgileTracker.air");
This will take care of installing the AIR runtime, installing the application, and launching it for the first time. installApplication has two more optional parameters. The AIR runtime that the application requires, and arguments that can be passed to the application for it's first run. Example:
api.installApplication("http://www.agileagenda.com/download/AgileTracker.air","1.0",["Arg1","Arg2"]);
That's all there is to it.
So that's it, pretty simple, huh? You might also want to look into using a LocalConnection to do realtime communication between your web-app and your air-app once the air-app has been launched. Recap of the links:
Wrapper Class:
Adobe's Documentation:
My Blog (where any updates to the wrapper class will be posted)
The actual air.swf that does all the heavy lifting (This URL is wrong in some of the docs!)
http://airdownload.adobe.com/air/browserapi/air.swf
