1. Home
2. Developer Connection
3. Adobe AIR Developer Center

Adobe AIR Article

 

Deploying AIR applications with the installer badge

David Tucker

DavidTucker.net

Adobe provides three assets that are essential to the deployment of AIR applications: the Adobe AIR install badge, the Adobe AIR browser API, and the Flash Player Detection Kit. When you use all of these tools, you can create a seamless installation process that installs the needed components for your AIR applications.

Requirements

In order to make the most of this article, you need the following software and files:

Adobe AIR SDK

• Download

Adobe Flash Player Detection Kit

• Download

Sample files:

• badge_install_samples (ZIP, 300K)

Prerequisite knowledge

The tutorial requires a basic knowledge of JavaScript and HTML. This tutorial also assumes that you know how to create an AIR application.

Using the install badge

Adobe provides the Adobe AIR install badge with the Adobe AIR SDK. The badge can be found in the samples/badge folder. The badge has two main functions:

• It verifies whether the user has the required version of Adobe AIR installed. If not, the badge will install the correct version.
• It installs your application on the user's computer.

Changes in the install badge

In the Adobe AIR SDK, some changes have been made to the install badge. The AIR SDK includes the browser API (air.swf) that allows for more secure detection and installation of the Adobe AIR and AIR applications. Previously, the logic for Adobe AIR detection was handled in the actual install badge.swf file. In AIR 1.0, the badge.swf file loads the browser API (a SWF file) from adobe.com that handles the actual core detection and operating system–specific logic. This helps Adobe to respond to any security or operating system changes quickly. It also enables Adobe to update automatically all of the badges that leverage remote loading of the core detection logic. (For more details, refer to the Adobe AIR Developer FAQ.) You can also download the browser API (air.swf) and include it in your custom badge if you like.

Using the example

The Adobe AIR SDK contains a sample implementation of the Adobe AIR install badge. This sample integrates the Flash Player Detection Kit. The first script block in the file defines the version of Flash Player that is required to run the install badge. At the time of writing, the required version is 9.0.115:

// 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;  

If this version of Flash Player is not installed, it will display alternate content which allows the user to manually install Adobe AIR and your application. Also, the tag <noscript> is used to define alternate content that will be displayed if the user's browser does not support JavaScript (or if the user has disabled it).

For this implementation to work properly, you need to update three sections of the code with information about your Adobe AIR application.

1. First, you will need to update the flashvars that are sent to the install badge. The following variables are defined in this section of code.

   • appname: The name of your Adobe AIR application (this variable must be URL encoded).
   • appurl: The URL of your Adobe AIR application's .air file. For testing locally, you can substitute the simple file name. However, the installation will fail if the user also needs to install Adobe AIR. For the AIR installation to function properly, it requires the full URL of your Adobe AIR application file.
   • airversion: The version number of Adobe AIR that is required to run your application. (The current version of Adobe AIR is 1.0.M6.)
   • imageurl (optional): The URL of the image that will be placed inside of the Adobe AIR install badge. (If it resides under a different domain than the install badge, a cross-domain policy file must be used.)
   • buttoncolor (optional): The hex color value of the button color, 000000 by default.
   • messagecolor (optional): The hex color value of the text below the button, 000000 by default.

   The corresponding code can be found on line 55 of the default_badge.html file in the Adobe AIR SDK:

   'flashvars','appname=Sample%20Application&appurl=http://www.davidtucker.net/airtips/sampleApplication-1.air'

2. Next, you need to update the alternate content that will be displayed when the user does not have the required version of the Flash Player or if the version cannot be detected:

   var alternateContent = '<table id="messageTable"><tr><td>'
   + 'This application requires the following be installed:<ol>'
   + '<li><a href="http://adobe.com/go/getair/">Adobe&#174; AIR&#8482; Runtime</a></li>'
   + '<li><a href="http://www.davidtucker.net/airtips/sampleApplication-1.air">Sample Application</a></li>'
   + '</ol>Please click on each link in the order above to complete the installation process.</td></tr></table>';

3. Finally, you will need to update the <noscript> block that is used when the browser does not support JavaScript (or has it disabled):

   <noscript>
   …
   <li><a href="http://www.davidtucker.net/airtips/sampleApplication-1.air">Sample Application</a></li>
   …
   </noscript>

Testing the example

If you have the latest version of Flash Player and the correct version of Adobe AIR, you should see the install badge (shown in Figure 1).

Figure 1. The Adobe AIR install badge

If you have the latest version of Flash Player, but you do not have the correct version of the AIR runtime, you should see the sequence of screens illustrated in Figure 2. The first screen demonstrates that the install badge has detected that the user does not have the required version of AIR installed.

Figure 2. Adobe AIR detection with the install badge

If users choose to install Adobe AIR, they will be directed to install both the AIR runtime as well as your application (see Figure 3).

Figure 3. Installing Adobe AIR with the install badge

If you do not have the latest version of the Flash Player installed (or if JavaScript is disabled in your browser), you should see the content shown in Figure 4. This will allow the user to install the needed items manually.

Figure 4. Alternate content when the latest version of Flash Player is not installed

Some browsers will present a warning when you try to run the sample files from your local machine. If you allow your browser to run the active content locally, the sample should display correctly.

Setting the proper mime type

If the user has to install your AIR application manually, you will need to verify that your server is properly configured to serve .air files. This configuration is made at the web server configuration level, so if you in a shared hosting environment, you may need to contact their system administrator and have it added manually.

The mime type declaration tells the server how to deliver files with a certain extension. If you are using Apache, this change will be included in the httpd.conf file. You will need to add the following line of code below the other AddType declarations:

AddType application/vnd.adobe.air-application-installer-package+zip .air

This will tell Apache to handle all files with a .air extension as an Adobe AIR installer package. This could easily be modified to work with other web servers as long as .air is mapped to the mime type application/vnd.adobe.air-application-installer-package+zip.

Integrating Express Install

Using the process outlined above could leave a large percentage of your potential users with a manual installation, because only users with the latest version of Flash Player can benefit from the convenience of the Adobe AIR install badge. However, using the Express Install feature of the Flash Player Detection Kit will allow you to have the user update his or her Flash Player without ever leaving your site.

The necessary files for this implementation are included with the exercise file for this article. They also can be obtained by downloading the Flash Player Detection Kit from Adobe.

How it works

For users to take advantage of Express Install they must have Flash Player version 6.0.65 or later installed. In that case, Express Install will attempt to determine what version of Flash Player the user has. If the version is less than the version that has been defined, Express Install will ask users if they would like to install the latest version of the Flash Player from your site (see Figure 5).

Figure 5. Using the Express Install feature

After the installation process is completed, the page will be reloaded, and the Flash content will be displayed correctly.

Using Express Install

The Express Install feature of the Flash Player Detection Kit adds a few steps to the version detection process. In a standard configuration the following steps are performed:

1. Verify whether the user has at least version 6.0.65 of Flash Player. If not, the alternate content will be shown.
2. Verify whether the user has at least the version of Flash Player that is defined in the script block at the top of the page. If not, the file playerProductInstall.swf will be loaded and the express installation will begin. A redirect URL is passed to the playerProductInstall.swf file (which is the current page by default). After the installation process is completed, this page will be reloaded.
3. When the correct version of Flash Player is detected, the correct Flash SWF file will be loaded.

Just as with Flash Player detection, the installation process requires JavaScript. If the user does not have JavaScript enabled, he or she will see only what is in the <noscript> block. The Flash Player Detection Kit contains a sample HTML file that integrates the Express Install feature. This file can serve as a template for when you need to integrate Express Install with your Flash movies.

Using the included script

The file InstallBadge.js that is included with this article's exercise files can be used to easily add the Express Install functionality with the Adobe AIR install badge. It combines code from the Adobe AIR SDK install badge example with the Flash Player Detection Kit Express Install example. It also detects what platform the user is using, and can direct he or she to the URL of the AIR installation if it cannot be installed automatically.

To properly integrate the Express Install functionality and simplify the code that will have to be modified, you will need to include a the following global variables in your document:

// 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.0.M6";
// 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";

You can also define the width, height, button color, message color, and a directory for each of the SWF files (documentation for InstallBadge.js can be found with the exercise files for this article). When the variables are defined, you can insert the two JavaScript files that are required to insert the AIR Install Badge. You will insert these in the position where you want the install badge to appear.

<script src="AC_RunActiveContent.js" language="javascript"></script>
<script src="InstallBadge.js" language="javascript"></script>

You will also need to add a <noscript> block manually. This will enable those users who have JavaScript disabled to manually install your application. To further streamline the process, you can insert the direct links to Adobe AIR for both Windows and Mac OS X. This enables users to install your application in only two clicks.

<noscript>
<table id="AIRDownloadMessageTable">
<tr><td>
Download <a href="http://www.davidtucker.net/sampleApplication.air">Sample Application</a> now.<br /><br />
<span id="AIRDownloadMessageRuntime">
This application requires the Adobe&#174;&nbsp;AIR&#8482; runtime to be installed for 
<a href="http://airdownload.adobe.com/air/mac/download/1.0/AdobeAIR.dmg">Mac OS</a> or 
<a href="http://airdownload.adobe.com/air/win/download/1.0/AdobeAIRInstaller.exe">Windows</a>.</span>
</td></tr>
</table>
</noscript>

If you now test the sample, it should function properly. If you don't have at least Flash Player version 9.0.115 installed, you should see the dialog box shown in Figure 3. If you don't have JavaScript enabled, you should see the manual installation instructions from Figure 2. After you click the Install Now button, the badge will install the application.

Where to go from here

With Adobe AIR 1.0, you can now detect and launch installed air applications. With the files included with this article, you can easily deploy your applications to virtually anyone on the Internet from your site. You also can easily extend this example and create your own badges in Flash or Flex using the example that is included with the Adobe AIR SDK. By doing this, you can create a badge that matches the look and feel of your site, or integrate an install badge into an already existing Flex application.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

About the author