觉得有实用价值,在此记录备忘
原文路径:
http://help.adobe.com/en_US/AIR/1.5/devappsflex/WS5b3ccc516d4fbf351e63e3d118666ade46-7e15.html
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.
For a demonstration of how to use the seamless install feature, see the Distributing an AIR Application via the Web(http://www.adobe.com/go/learn_air_qs_seamless_install_en) quick start sample article.
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, seeInter-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
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.”
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.
Navigate to the HTML page in a web browser that has Flash Player (version 9 update 3 or later on Windows and Mac OS, or version 10 on Linux) installed.
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.
Installs the application into /opt.
Creates a desktop shortcut for application
Creates a Start Menu shortcut
Adds an entry for application in the system package manager
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
Modifying the badge.swf file
The Flex SDK provides the source files for the badge.swf file. These files are included in the samples/badge folder of the SDK:
Source files | Description |
---|---|
badge.fla | The source Flash file used to compile the badge.swf file. The badge.fla file compiles into a SWF 9 file (which can be loaded in Flash Player). |
AIRBadge.as | An ActionScript 3.0 class that defines the base class used in the basdge.fla file. |
You can use Flash CS3 or Flash CS4 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:
Method | Description |
---|---|
getStatus() | Determines whether the runtime is installed (or can be installed) on the computer. For details, see Checking if the runtime is installed. |
installApplication() | Installs the specified application on the user’s machine. For details, see Installing an 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:
Note: The badge.swf file, provided with the Flex SDK, automatically loads the air.swf file. See Using the badge.swf file to install an AIR application. The instructions in this section apply to creating your own SWF file that loads the air.swf file.
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:
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:
Parameters | Description |
---|---|
appID | The application ID for the application. For details, see Defining the application identity. |
pubID | 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 fromhttp://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:
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:
<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:
Parameter | Description |
---|---|
appID | The application ID for the application to launch. For details, see Defining the application identity. |
pubID | 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.
Before presenting the user interface to launch the application, you may want to call the getApplicationVersion() method in the air.swf file. For details, seeChecking 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.
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.