Chapter 17. AIR Application Distribution with the Browser API
After you create your AIR application, you will need a reliable means of distributing your application to its potential users. The AIR Browser API enables developers to distribute their applications via the browser so that the install process is as seamless as possible for the end user. When you use the Browser API, you can prevent a user from having to install AIR separately from your application. This means the user can install your application without ever leaving your site and in as few steps as possible.
In addition, the Browser API provides functionality beyond installation. For example, you can launch an AIR application from the browser. Additionally, you can determine valuable pieces of information about the user’s environment including whether the user has AIR installed, whether the user has your application installed, and what version of your application is installed.
Including the Browser API
Problem
You need to include the Browser API in a Flash movie to interact with an AIR application from the Web.
Solution
Include the Browser API SWF in your application to gain the needed functionality.
Discussion
To utilize any of the Browser API functionality, it must first be included in your application. Adobe hosts the SWF for the Browser API at http://airdownload.adobe.com/air/browserapi/air.swf. You can load this SWF into your Flash, Flex, or SWF-based AIR application to provide the Browser API functionality.
This snippet demonstrates how to include the Browser API SWF in your application:
private const BROWSERAPI_URL_BASE: String =
"http://airdownload.adobe.com/air/browserapi";
private var _loader:Loader;
private var _air:Object;
public function handleCreationComplete():void {
_loader = new Loader();
var loaderContext:LoaderContext = new LoaderContext();
loaderContext.applicationDomain = ApplicationDomain.currentDomain;
_loader.contentLoaderInfo.addEventListener(Event.INIT, onInit);
_loader.load(new URLRequest(BROWSERAPI_URL_BASE + "/air.swf"), loaderContext);
}
private function onInit(e:Event):void {
_air = e.target.content;
}Detecting the Installed Version of AIR
Solution
Access the runtimeVersion property of the
NativeApplication instance to determine which version
of AIR is installed.
Discussion
There are times when you want to determine which version of AIR is
running on the user’s computer. While technically part of the Browser
API, this can allow you to warn the user if the updated version of your
application will require an update to the runtime as well. The
NativeApplication class instance that is at
NativeApplication.nativeApplication contains a
property, runtimeVersion, that contains the current
runtime on the user’s computers. In addition, there is also a property,
runtimePatchLevel, that will return just the patch
level for the current version. The runtimeVersion
property contains both the major release version as well as the patch
level.
ActionScript/Flex
In this example, a Flex application detects the version of AIR that is installed on the user’s computer:
<?xml version="1.0" encoding="utf-8"?>
<mx: Application
xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
horizontalAlign="center"
verticalAlign="middle">
<mx:Label text="Installed AIR Version:
{NativeApplication.nativeApplication.runtimeVersion}"
fontWeight="bold" />
</mx: Application>JavaScript
In this example, a JavaScript application detects the version of AIR that is installed on the user’s computer:
<html>
<head>
<title>Application Sandbox sample</title>
<script type="text/javascript" src="AIRAliases.js"></script>
<script type="text/javascript">
function getAIRVersion() {
var version = document.getElementById("version");
version.innerHTML =
air.NativeApplication.nativeApplication.runtimeVersion;
}
</script>
</head>
<body onload="getAIRVersion()">
<h3>AIR Version</h3>
<div id="version"></div>
</body>
</html>Launching an AIR Application from the Browser
Solution
Use the Browser API’s launchApplication method to launch an approved
AIR application from the browser.
Discussion
The Browser API gives you the ability to launch an AIR application
from a web-based SWF, but this method has a few limitations. First, this
functionality works only on AIR applications that allow it. If the
allowBrowserInvocation
setting in the application descriptor file (see Chapter 2) is set to true, then the application can be launched
from the browser. If it is not set to true (it defaults to false), the invoked application will never
launch. Second, the launching of the application must be triggered by a
user gesture (in most cases a mouse click). This is a purposeful
limitation that keeps SWFs from launching an AIR application without the
user’s knowledge.
You can launch applications by using the Browser API’s launchApplication method. To use this approach, you will need two pieces of
information: the application ID of the AIR application and the publisher
ID of the AIR application.
Finding the Publisher ID
The publisher ID is defined only when an application is packaged and is
always null when launching your
application from adl. You can
determine this value in two ways. You can check NativeApplication.nativeApplication.publisherID
for the publisher ID at runtime; alternatively, any time after the
application is installed, you can navigate to the installation
directory and consult the META-INF/AIR/publisherid file, which
contains the publisher ID.
This recipe’s examples use a sample AIR application. This
application has no real UI or controls; rather, it just displays
“Application Launched” when the application opens. For this sample,
the application ID is com.oreilly.aircookbook.as.17.3, and the
publisher ID is 9F542B7BA834BBBF0CA61BF006C9E4312C42DDE6.1.
If you want to see the sample work with your application, be sure to
modify these parameters accordingly.
Using the Browser API
To use the Browser API to launch an AIR application, you
first have to load the Browser API into your application. Next, you
need to call the launchApplication
method, which takes three parameters: the application ID, the
publisher ID, and an array of arguments. The first two parameters are
required, but you are not obligated to pass in any arguments.
In this example, the user interface consists of a single button that launches the application. This button is enabled once the Browser API SWF is loaded.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
layout="absolute"
creationComplete="handleCreationComplete()">
<mx:Script>
<![CDATA[
private const BROWSERAPI_URL_BASE: String =
"http://airdownload.adobe.com/air/browserapi";
private var _loader:Loader;
private var _air:Object;
public function handleCreationComplete():void {
_loader = new Loader();
var loaderContext:LoaderContext = new LoaderContext();
loaderContext.applicationDomain =
ApplicationDomain.currentDomain;
_loader.contentLoaderInfo.addEventListener(Event.INIT, onInit);
_loader.load(new URLRequest(BROWSERAPI_URL_BASE + "/air.swf"),
loaderContext);
}
private function onInit(e:Event):void {
_air = e.target.content;
launchButton.enabled = true;
}
private function handleClick( event:MouseEvent ):void {
_air.launchApplication( "com.oreilly.aircookbook.as.17.3",
"9F542B7BA834BBBF0CA61BF006C9E4312C42DDE6.1" );
}
]]>
</mx:Script>
<mx:Button id="launchButton" label="Launch Application" enabled="false"
click="handleClick(event)" />
</mx:Application>Here is the code to build a sample AIR application that offers its publisher ID for use in the previous example:
Decscriptor:
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/air/application/1.5">
<id>com.oreilly.aircookbook.as.17.3</id>
<filename>aircookbook.17.3</filename>
<name>aircookbook.as.17.3</name>
<version>v1</version>
<initialWindow>
<content>ch17_3.swf</content>
</initialWindow>
<allowBrowserInvocation>true</allowBrowserInvocation>
</application>
The application code:
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
<mx:Text text="THIS IS AN EXAMPLE APPLICATION" />
<mx:Text text="{NativeApplication.nativeApplication.publisherID}" />
</mx:WindowedApplication>Installing an AIR Application from the Browser
Problem
You want to implement a custom installation solution in the browser, such as a one-click install from an online Flash or Flex application.
Solution
Use the install method found in the Browser API to attach the installation of an AIR application to a Flex or Flash UI control.
Discussion
The easiest means of installing an AIR application from the browser is using one of the install badges, which use the Browser API to perform the installation (for more information on the install badges, see Using the Included Seamless Install Badge). In cases where you want to customize the experience beyond the standard install badge, though, you can utilize the Browser API to provide similar functionality.
After you include the Browser API in your application, the three
methods you need to use are getStatus
to determine whether AIR is installed (or available for the operating
system), getApplicationVersion to
determine which (if any) version of the application is installed on the
operating system, and installApplication to perform the actual
installation.
The getStatus method returns a string that indicates the status of AIR on the
user’s machine. It returns three possible values:
installed: Indicates that AIR is already installed on the user’s machineavailable: Indicates that AIR is not installed on the user’s machine but it is available for the user’s platformunavailable: Indicates that AIR is not installed on the user’s machine and there is not a current version of the runtime for the user’s platform
The installApplication
method takes three parameters: the absolute URL for the packaged
AIR file, the version of AIR that is required, and an array of
arguments. The arguments are optional and are passed to the
application’s install process if present. If the user does not have AIR
installed, it will be installed with the AIR application. However, you
will want to be sure that AIR is available for the user’s platform to
prevent any unwanted errors from being displayed. It is best to call the
getStatus method if you are planning
to call the installApplication
method.
The getApplicationVersion
method takes three parameters. First, you pass in the
application ID. Second, you pass in the publisher ID. Finally, you pass
in a callback method that will be executed when the value is returned.
The callback method will be passed the application version as a
string.
In this example, a sample application is located at http://www.davidtucker.net/staging/TargetApplication.air.
The application ID and publisher ID are also included in the code. The
user interface for this example consists of a button that triggers the
application installation and a label that indicates the status to the
user. First, the Browser API is loaded. Then, upon initialization, the
getStatus method is called. If the
status (and, consequently, AIR) is installed or available, the install button is enabled. If
the AIR status is installed, the
application also calls the getApplicationVersion method to determine
whether the application has already been installed.
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
horizontalAlign="center"
verticalAlign="middle"
creationComplete="handleCreationComplete()">
<mx:Script>
<![CDATA[
private const BROWSERAPI_URL_BASE: String =
"http://airdownload.adobe.com/air/browserapi";
private var _loader:Loader;
private var _air:Object;
public function handleCreationComplete():void {
_loader = new Loader();
var loaderContext:LoaderContext = new LoaderContext();
loaderContext.applicationDomain =
ApplicationDomain.currentDomain;
_loader.contentLoaderInfo.addEventListener(Event.INIT, onInit);
_ loader.load(new URLRequest(BROWSERAPI_URL_BASE + "/air.swf"),
loaderContext);
}
private function onInit(e:Event):void {
_air = e.target.content;
var airStatus:String = _air.getStatus();
switch( airStatus ) {
case "installed":
_air.getApplicationVersion(
"com.oreilly.aircookbook.as.17.3", "9F542B7BA834BBBF0CA61BF006C9E4312C42DDE6.1",
handleApplicationVersion );
break;
case "available":
statusLabel.text = "AIR will need to be installed for
this application";
installButton.enabled;
break;
case "unavailable":
statusLabel.text = "AIR is not available for your platform";
break;
}
}
private function handleApplicationVersion( version:String ):void
{
if( version != null ) {
statusLabel.text = "Version Installed: " + version;
installButton.enabled = false;
} else {
statusLabel.text = "Application Not Installed";
installButton.enabled = true;
}
}
private function handleClick( event:MouseEvent ):void
{
_air.installApplication(
"http://www.davidtucker.net/staging/TargetApplication.air", "1.5" );
}
]]>
</mx:Script>
<mx:Button id="installButton" label="Install Application" enabled="false"
click="handleClick(event)" />
<mx:Label id=" statusLabel " />
</mx:WindowedApplication>Remember that the installation must be
triggered by a user gesture. In this case, you couldn’t call the
installApplication method at any
point; it has to be on the mouse click. This is a security feature baked
into the Browser API that prevents you from launching or installing an
application without the user’s knowledge or consent.
Using the Included Seamless Install Badge
Problem
You need a prebuilt and easy-to-implement way to install an AIR application from the browser.
Solution
Use the seamless install badge from Adobe.
Discussion
An install badge allows any user with Flash Player version 9.0.115 or newer installed to install an AIR application from the Web. In addition, if the user does not have AIR installed, AIR automatically installs with the application. When paired with the Flash Player Express Install functionality, install badges enable users to upgrade Flash Player to the needed level before attempting to install the AIR application.
Note
At the time this book was being written, Adobe had just released a new AIR application that simplifies the creation of a customized install badge. This application is called Badger, and more information can be found here: http://www.adobe.com/devnet/air/articles/badger_for_air_apps.html
The entire install badge process is outlined clearly at the Adobe AIR Developer Center. The article located at http://www.adobe.com/devnet/air/articles/air_badge_install.html includes sample code that will be used in this entry. The code includes the badge items as well as the SWF files needed for the express installation process. To follow along, download the exercise files that are included with the article.
Note
In addition to the install badge included with the Adobe AIR SDK, a second badge is available on the Adobe AIR Developer Center site at http://www.adobe.com/devnet/air/articles/badge_for_air.html.
Configuring the Install Badge
First, be sure you have downloaded the files from the Adobe AIR Developer Center article mentioned earlier. To insert the install badge into a page, you need to extract all the files from the expressInstallDirectory directory into the folder where your page will reside. One of the files in the expressInstallDirectory is a sample index.html file that, among other things, defines the settings for the install badge (see Figure 17-1). You can edit these settings, found at the top of the file, to be specific to your AIR application.
The badge allows you to define an image that will be displayed as a preview of your application. You must also define the URL of your application and the required version of AIR for your application.
<script language="JavaScript" type="text/javascript"> <!-- // ----------------------------------------------------------------------------- // Globals // Major version of Flash required var requiredMajorVersion = 9; // Minor version of Flash required var requiredMinorVersion = 0; // Minor version of Flash required var requiredRevision = 115; // AIR Version Required var airVersion = "1.5"; // AIR Application Name var airApplicationName = "Sample Application"; // AIR Application URL var airApplicationURL = "http://www.davidtucker.net/staging/TargetApplication.air"; // AIR Application Image var airApplicationImage = "sample.jpg"; // ----------------------------------------------------------------------------- // --> </script>
In addition, you will need to edit the index.html file’s noscript code block and update it with the
values for your application:
<!-- Noscript Block for users with JavaScript Disabled -->
<noscript>
<table id="AIRDownloadMessageTable">
<tr>
<td>
Download <a
href="http://www.davidtucker.net/staging/TargetApplication.air">Sample
Application</a> now.<br /><br />
<span id="AIRDownloadMessageRuntime">
This application requires the Adobe® AIR™ runtime to be
installed for <a href="http://airdownload.adobe.com/air/mac/download/1.5/
AdobeAIR.dmg">Mac OS</a> or <a href="http://airdownload.adobe.com/air/win/
download/1.5/AdobeAIRInstaller.exe">Windows</a>.</span>
</td>
</tr>
</table>
</noscript>
Once this code is in place, the AIR badge (Figure 17-2) should now be properly configured for your application.
For reference, the following is the completed index.html file in its entirety. For this code to work properly, you must be sure the needed SWF and JavaScript files are included in the same directory as your index.html file.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Adobe AIR Application Installer Page</title>
<script language="JavaScript" type="text/javascript">
<!--
// -----------------------------------------------------------------------------
// Globals
// Major version of Flash required
var requiredMajorVersion = 9;
// Minor version of Flash required
var requiredMinorVersion = 0;
// Minor version of Flash required
var requiredRevision = 115;
// AIR Version Required
var airVersion = "1.5";
// AIR Application Name
var airApplicationName = "Sample Application";
// AIR Application URL
var airApplicationURL = "http://www.davidtucker.net/airtips/sampleApplication-1.air";
// AIR Application Image
var airApplicationImage = "sample.jpg";
// -----------------------------------------------------------------------------
// -->
</script>
</head>
<body>
<div id="flashContent">
<!-- Insert the Installer JavaScript -->
<script src="AC_RunActiveContent.js" language="javascript"></script>
<script src="InstallBadge.js" language="javascript"></script>
<!-- Noscript Block for users with JavaScript Disabled -->
<noscript>
<table id="AIRDownloadMessageTable">
<tr>
<td>
Download <a
href="http://www.davidtucker.net/airtips/sampleApplication.air">Sample
Application</a> now.<br /><br />
<span id="AIRDownloadMessageRuntime">
This application requires the Adobe® AIR™ runtime to
be installed for <a href="http://airdownload.adobe.com/air/mac/download/1.5/
AdobeAIR.dmg">Mac OS</a> or <a href="http://airdownload.adobe.com/air/win/
download/1.5/AdobeAIRInstaller.exe">Windows</a>.</span>
</td>
</tr>
</table>
</noscript>
</div>
</body>
</html>