AIR.SWF in-browser APICustomizing the seamless install badge.swfIn 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:
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). 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, or later, 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 example, 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 applicationIncluded 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. Embed the badge.swf file in a web page
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 Modify the badge.swf file. Install the AIR application from a seamless install link in a web pageOnce 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.
Modify the badge.swf fileThe Flex SDK and AIR SDK provids the source files for the badge.swf file. These files are included in the samples/badge folder of the SDK:
You can use Flash Professional 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 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). 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 fileYou 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. Note: The badge.swf file, provided with the AIR SDK
and 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 installedA 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. Checking from a web page if an AIR application is installedA 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. 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 browserA 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). Launching an installed AIR application from the browserTo 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). 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.
|
|