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 Flex SDK 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.

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.

Important: The features described in this section
(and the APIs in the air.swf file) require the end user to have
Adobe® Flash® Player 9 update 3 installed in the web browser on
Windows or Mac OS. On Linux, the seamless install feature requires
Flash Player 10 (version 10,0,12,36 or later). You can write code
to check the installed version of Flash Player and provide an alternate
interface to the user if the required version of Flash Player is
not installed. For instance, if an older version of Flash Player is
installed, you could provide a link to the download version of the
AIR file (instead of using the badge.swf file or the air.swf API
to install an application).

Using the badge.swf file to install an AIR application

Included
in 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 web site.

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

Locate the following
files, provided in the samples/badge directory of the Flex SDK,
and add them to your web server.

badge.swf

default_badge.html

AC_RunActiveContent.js

Open the default_badge.html page in a text editor.

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).

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.

Rename the default_badge.html file and adjust its code (or
include it in another HTML page) to suit your needs.

Note: For
the HTML embed tag that loads the badge.swf file,
do not set the wmode attribute; leave it set to
the default setting ("window"). Other wmode settings
will prevent installation on some systems. Also, using other wmode settings
produces an error: “Error #2044: Unhandled ErrorEvent:. text=Error
#2074: The stage is too small to fit the download ui.”

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:

url—A
string defining the URL. You must use an absolute, not relative,
URL path.

runtimeVersion—A string indicating the version
of the runtime (such as "1.0.M6") required by the application
to be installed.

arguments— Arguments to be passed to the
application if it is launched upon installation. The application is
launched upon installation if the allowBrowserInvocation element
is set to true in the application descriptor file.
(For more information on the application descriptor file, see Setting AIR application properties.) If the application is launched
as the result of a seamless install from the browser (with the user
choosing to launch upon installation), the application’s NativeApplication
object dispatches a BrowserInvokeEvent object only if arguments
are passed. Consider the security implications of data that you
pass to the application. For details, see Launching an installed AIR application from the browser.

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

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:

String value

Description

"available"

The runtime can be installed on this computer
but currently it is not installed.

"unavailable"

The runtime cannot be installed on this
computer.

"installed"

The runtime is installed on this 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.

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:

The publisher ID for the application. For
details, see About AIR publisher identifiers. If the application in question
does not have a publisher ID, set the pubID parameter
to an empty string (“”).

callback

A callback function to serve as the handler
function. The getApplicationVersion() method operates asynchronously,
and upon detecting the installed version (or lack of an installed
version), this callback method is invoked. The callback method definition
must include one parameter, a string, which is set to the version
string of the installed application. If the application is not installed,
a null value is passed to the function, as illustrated in the previous
code sample.

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.

Note: As of AIR 1.5.3, the publisher ID is deprecated. Publisher
IDs are no longer assigned to an application automatically. For
backward compatibility, applications can continue to specify a publisher
ID.

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:

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

Parameter

Description

url

A string defining the URL of the AIR file
to install. You must use an absolute, not relative, URL path.

runtimeVersion

A string indicating the version of the runtime
(such as "1.0") required by the application to be installed.

arguments

An array of arguments to be passed to the
application if it is launched upon installation. Only alphanumerical characters
are recognized in the arguments. If you need to pass other values,
consider using an encoding scheme.

The application is launched
upon installation if the allowBrowserInvocation element
is set to true in the application descriptor file.
(For more information on the application descriptor file, see Setting AIR application properties.) If the application is launched
as the result of a seamless install from the browser (with the user choosing
to launch upon installation), the application’s NativeApplication
object dispatches a BrowserInvokeEvent object only if arguments
have been passed. For details, see Launching an installed AIR application from the browser.

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 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:

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:

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 publisher ID for the application to
launch. For details, see About AIR publisher identifiers. If the application in question
does not have a publisher ID, set the pubID parameter
to an empty string (“”)

arguments

An array of arguments to pass to the application.
The NativeApplication object of the application dispatches a BrowserInvokeEvent
event that has an arguments property set to this array. Only alphanumerical
characters are recognized in the arguments. If you need to pass
other values, consider using an encoding scheme.

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.

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.

Note: As of AIR 1.5.3, the publisher ID is deprecated. Publisher
IDs are no longer assigned to an application automatically. For
backward compatibility, applications can continue to specify a publisher
ID.