We’ve all seen the AIR installation badges that let you install an AIR application from a website. But the API exposed to do that lets you do more than just a simple badge. I’ve been working on a web-based service for AgileAgenda. One of the components of that is to manage the list of files you’ve saved to the service and be able to open those in the desktop AIR application. So right from within the online Flex based app it sure would be nice to detect if the application is installed, give the user the option to install, and then launch it for them and automatically open the desired file. Something like this…
- Detect whether or not the application is installed.
- Display the version number if it is. (Disable the “Open schedule in…” button if it’s not)
- When clicking on the “Open” link, launch the application with a few parameters so it know what to open.
- When clicking on the “Install” link, install the application and pass a few parameters so it know what to open when it launches directly after the install.
<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:
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
api.launchApplication( “com.agileagenda.AgileTracker”, “F49A4D8DF78A1FEE7A3BE440DC11BAB18D922274.1″ );
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:
http://airdownload.adobe.com/air/browserapi/air.swf
