AIR.SWF in-browser API

In addition to using the badge.swf file provided with the SDK, you can create your own SWF file for use in a browser page. Your custom SWF file can interact with the runtime in the following ways:

• It can install an AIR application. See Installing an AIR application from the browser.

• It can check to see if a specific AIR application is installed. See Checking from a web page if an AIR application is installed.

• It can check to see if the runtime is installed. See Checking if the runtime is installed.

• It can launch an installed AIR application on the user’s system. See Launching an installed AIR application from the browser.

These capabilities are all provided by calling APIs in a SWF file hosted at adobe.com: air.swf. You can customize the badge.swf file and call the air.swf APIs from your own SWF file.

Additionally, a SWF file running in the browser can communicate with a running AIR application by using the LocalConnection class. For more information, see Communicating with other Flash Player and AIR instances (for ActionScript developers) or Communicating with other Flash Player and AIR instances (for HTML developers).

Included in the AIR SDK and the Flex SDK is a badge.swf file which lets you easily use the seamless install feature. The badge.swf can install the runtime and an AIR application from a link in a web page. The badge.swf file and its source code are provided to you for distribution on your website.

You can create your own SWF file that uses the APIs in the air.swf file to interact with the runtime and AIR applications from a web page in a browser. The air.swf file is hosted at http://airdownload.adobe.com/air/browserapi/air.swf. To reference the air.swf APIs from your SWF file, load the air.swf file into the same application domain as your SWF file. The following code shows an example of loading the air.swf file into the application domain of the loading SWF file:

var airSWF:Object; // This is the reference to the main class of air.swf 
var airSWFLoader:Loader = new Loader(); // Used to load the SWF 
var loaderContext:LoaderContext = new LoaderContext();  
                                // Used to set the application domain  
 
loaderContext.applicationDomain = ApplicationDomain.currentDomain; 
 
airSWFLoader.contentLoaderInfo.addEventListener(Event.INIT, onInit); 
airSWFLoader.load(new URLRequest("http://airdownload.adobe.com/air/browserapi/air.swf"),  
                    loaderContext); 
 
function onInit(e:Event):void  
{ 
    airSWF = e.target.content; 
}

Once the air.swf file is loaded (when the Loader object’s contentLoaderInfo object dispatches the init event), you can call any of the air.swf APIs, described in the sections that follow.

A SWF file can check if the runtime is installed by calling the getStatus() method in the air.swf file loaded from http://airdownload.adobe.com/air/browserapi/air.swf. For details, see Loading the air.swf file.

Once the air.swf file is loaded, the SWF file can call the air.swf file’s getStatus() method as in the following:

var status:String = airSWF.getStatus();

The getStatus() method returns one of the following string values, based on the status of the runtime on the computer:

The getStatus() method throws an error if the required version of Flash Player (version 9 update 3 or later on Windows and Mac OS, or version 10 on Linux) is not installed in the browser.

A SWF file can check if an AIR application (with a matching application ID and publisher ID) is installed by calling the getApplicationVersion() method in the air.swf file loaded from http://airdownload.adobe.com/air/browserapi/air.swf. For details, see Loading the air.swf file.

Once the air.swf file is loaded, the SWF file can call the air.swf file’s getApplicationVersion() method as in the following:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
airSWF.getApplicationVersion(appID, pubID, versionDetectCallback); 
 
function versionDetectCallback(version:String):void 
{ 
    if (version == null) 
    { 
        trace("Not installed."); 
        // Take appropriate actions. For instance, present the user with 
        // an option to install the application. 
    } 
    else 
    { 
        trace("Version", version, "installed."); 
        // Take appropriate actions. For instance, enable the 
        // user interface to launch the application. 
    } 
}

The getApplicationVersion() method has the following parameters:

The getApplicationVersion() method throws an error if the required version of Flash Player (version 9 update 3 or later on Windows and Mac OS, or version 10 on Linux) is not installed in the browser.

A SWF file can install an AIR application by calling the installApplication() method in the air.swf file loaded from http://airdownload.adobe.com/air/browserapi/air.swf. For details, see Loading the air.swf file.

Once the air.swf file is loaded, the SWF file can call the air.swf file’s installApplication() method, as in the following code:

var url:String = "http://www.example.com/myApplication.air"; 
var runtimeVersion:String = "1.0"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.installApplication(url, runtimeVersion, arguments); 

The installApplication() method installs the specified application on the user’s machine. This method has the following parameters:

The installApplication() method can only operate when called in the event handler for a user event, such as a mouse click.

The installApplication() method throws an error if the required version of Flash Player (version 9 update 3 or later on Windows and Mac OS, or version 10 on Linux) is not installed in the browser.

On Mac OS, to install an updated version of an application, the user must have adequate system privileges to install to the application directory (and administrative privileges if the application updates the runtime). On Windows, a user must have administrative privileges.

You may also call the getApplicationVersion() method of the air.swf file to check if an application is already installed. You can call this method either before the application installation process begins or after the installation is started. For details, see Checking from a web page if an AIR application is installed. Once the application is running, it can communicate with the SWF content in the browser by using the LocalConnection class. For more information, see Communicating with other Flash Player and AIR instances (for ActionScript developers) or Communicating with other Flash Player and AIR instances (for HTML developers).

To use the browser invocation feature (allowing it to be launched from the browser), the application descriptor file of the target application must include the following setting:

<allowBrowserInvocation>true</allowBrowserInvocation>

For more information on the application descriptor file, see AIR application descriptor files.

A SWF file in the browser can launch an AIR application by calling the launchApplication() method in the air.swf file loaded from http://airdownload.adobe.com/air/browserapi/air.swf. For details, see Loading the air.swf file.

Once the air.swf file is loaded, the SWF file can call the air.swf file’s launchApplication() method, as in the following code:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.launchApplication(appID, pubID, arguments);

The launchApplication() method is defined at the top level of the air.swf file (which is loaded in the application domain of the user interface SWF file). Calling this method causes AIR to launch the specified application (if it is installed and browser invocation is allowed, via the allowBrowserInvocation setting in the application descriptor file). The method has the following parameters:

The launchApplication() method can only operate when called in the event handler for a user event, such as a mouse click.

The launchApplication() method throws an error if the required version of Flash Player (version 9 update 3 or later on Windows and Mac OS, or version 10 on Linux) is not installed in the browser.

If the allowBrowserInvocation element is set to false in the application descriptor file, calling the launchApplication() method has no effect.

Before presenting the user interface to launch the application, you may want to call the getApplicationVersion() method in the air.swf file. For details, see Checking from a web page if an AIR application is installed.

When the application is invoked via the browser invocation feature, the application’s NativeApplication object dispatches a BrowserInvokeEvent object. For details, see Invoking an AIR application from the browser (for ActionScript developers) or Invoking an AIR application from the browser (for HTML developers).

If you use the browser invocation feature, be sure to consider security implications. These implications are described in Invoking an AIR application from the browser (for ActionScript developers) and Invoking an AIR application from the browser (for HTML developers).

Once the application is running, it can communicate with the SWF content in the browser by using the LocalConnection class. For more information, see Communicating with other Flash Player and AIR instances (for ActionScript developers) or Communicating with other Flash Player and AIR instances (for HTML developers).