The seamless install feature lets you embed a SWF file in a web page that lets the user install an AIR application from the browser. If the runtime is not installed, the seamless install feature installs the runtime. The seamless install feature lets users install the AIR application without saving the AIR file to their computer. Included in the is a badge.swf file, which lets you easily use the seamless install feature. For details, see Using the badge.swf file to install an AIR application.

Contents

• About customizing the seamless install badge.swf
• Using the badge.swf file to install an AIR application
• Loading the air.swf file
• Checking if the runtime is installed
• Checking from a web page if an AIR application is installed
• Installing an AIR application from the browser
• Launching an installed AIR application from the browser

About customizing the seamless install badge.swf

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. This section describes how to use and customize the badge.swf file and how to 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 Inter-application communication.

Using the badge.swf file to install an AIR application

Included in the 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.

The instructions in this section provide information on setting parameters of the badge.swf file provided by Adobe. We also provide the source code for the badge.swf file, which you can customize.

Embedding the badge.swf file in a web page

1. Locate the following files, provided in the samples/badge directory of the, and add them to your web server.
   • badge.swf
   • default_badge.html
   • AC_RunActiveContent.js
2. Open the default_badge.html page in a text editor.
3. In the default_badge.html page, in the AC_FL_RunContent() JavaScript function, adjust the FlashVars parameter definitions for the following:

   Parameter	Description
   appname	The name of the application, displayed by the SWF file when the runtime is not installed.
   appurl	(Required). The URL of the AIR file to be downloaded. You must use an absolute, not relative, URL.
   airversion	(Required). For the 1.0 version of the runtime, set this to 1.0.
   imageurl	The URL of the image (optional) to display in the badge.
   buttoncolor	The color of the download button (specified as a hex value, such as FFCC00).
   messagecolor	The color of the text message displayed below the button when the runtime is not installed (specified as a hex value, such as FFCC00).

4. The minimum size of the badge.swf file is 217 pixels wide by 180 pixels high. Adjust the values of the width and height parameters of the AC_FL_RunContent() function to suit your needs.
5. Rename the default_badge.html file and adjust its code (or include it in another HTML page) to suit your needs.

You can also edit and recompile the badge.swf file. For details, see Modifying the badge.swf file.

Installing the AIR application from a seamless install link in a web page

Once you have added the seamless install link to a page, the user can install the AIR application by clicking the link in the SWF file.

1. Navigate to the HTML page in a web browser that has Flash Player (version 9 update 3 or later) installed.
2. In the web page, click the link in the badge.swf file.
   • If you have installed the runtime, skip to the next step.
   • If you have not installed the runtime, a dialog box is displayed asking whether you would like to install it. Install the runtime (see Adobe AIR installation), and then proceed with the next step.
3. In the Installation window, leave the default settings selected, and then click Continue.

   On a Windows computer, AIR automatically does the following:

   • Installs the application into c:\Program Files\
   • Creates a desktop shortcut for application
   • Creates a Start Menu shortcut
   • Adds an entry for application in the Add/Remove Programs Control Panel

   On Mac OS, the installer adds the application to the Applications directory (for example, in the /Applications directory in Mac OS).

4. Select the options you want, and then click the Install button.
5. When the installation is complete, click Finish.

Modifying the badge.swf file

The provides the source files for the badge.swf file. These files are included in the src folder of the SDK:

You can use Flash CS3 to redesign the visual interface of the badge.fla file.

The AIRBadge() constructor function, defined in the AIRBadge class, loads the air.swf file hosted at http://airdownload.adobe.com/air/browserapi/air.swf. The air.swf file includes code for using the seamless install feature.

The onInit() method (in the AIRBadge class) is invoked when the air.swf file is loaded successfully:

private function onInit(e:Event):void {
    _air = e.target.content;
    switch (_air.getStatus()) {
        case "installed" :
            root.statusMessage.text = "";
            break;
        case "available" :
            if (_appName && _appName.length > 0) {
                root.statusMessage.htmlText = "<p align='center'><font color='#" 
                        + _messageColor + "'>In order to run " + _appName + 
                        ", this installer will also set up Adobe® AIR™.</font></p>";
            } else {
                root.statusMessage.htmlText = "<p align='center'><font color='#" 
                        + _messageColor + "'>In order to run this application, "
                        + "this installer will also set up Adobe® AIR™.</font></p>";
            }
            break;
        case "unavailable" :
            root.statusMessage.htmlText = "<p align='center'><font color='#" 
                        + _messageColor 
                        + "'>Adobe® AIR™ is not available for your system.</font></p>";
            root.buttonBg_mc.enabled = false;
            break;
    }
}

The code sets the global _air variable to the main class of the loaded air.swf file. This class includes the following public methods, which the badge.swf file accesses to call seamless install functionality:

The settings for url and runtimeVersion are passed into the SWF file via the FlashVars settings in the container HTML page.

If the application starts automatically upon installation, you can use LocalConnection communication to have the installed application contact the badge.swf file upon invocation. For details, see Inter-application communication

You may also call the getApplicationVersion() method of the air.swf file to check if an application is installed. You can call this method either before the application installation process or after the installation is started. For details, see Checking from a web page if an AIR application is installed.

Loading the air.swf file

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/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. These APIs are described in these sections:

• Checking if the runtime is installed
• Checking from a web page if an AIR application is installed
• Installing an AIR application from the browser
• Launching an installed AIR application from the browser

Checking if the runtime is installed

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 upgrade 3) is not installed in the browser.

Checking from a web page if an AIR application is installed

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 upgrade 3) is not installed in the browser.

Installing an AIR application from 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.M6";
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 upgrade 3) 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 details, see Inter-application communication.

Launching an installed AIR application from the browser

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 Setting AIR application properties.

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 upgrade 3) 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 Browser invocation.

If you use the browser invocation feature, be sure to consider security implications, described in Browser invocation.

Once the application is running, it can communicate with the SWF content in the browser by using the LocalConnection class. For details, see Inter-application communication.