packaging_and_deploying_the_air

2.8. Packaging and Deploying the AIR Application

Now that we understand how to build, test, and debug an AIR application, we are ready to create an AIR file that will allow us to deploy and distribute our application.

2.8.1. What Is an AIR File?

An AIR file is a ZIP-based application distribution package that is used to distribute AIR applications. It contains all of the files necessary to install and run an AIR application, and Adobe AIR uses it to create and install an AIR application onto the user's system.

The AIR file is created by the ADT command-line tool included in the AIR SDK and is used to distribute the application to other users.

NOTE

Installing an AIR file requires that Adobe AIR already be installed on the user's system.

An AIR file requires a minimum of two files: the application descriptor file and a root application file. However, you can also include other files, icons, directories, and assets that will be bundled with the AIR file and installed alongside your application. These files will then be available to the application at runtime.

In addition, you will also need a certificate to digitally sign your application.

2.8.2. Digitally Signing AIR Files

Adobe AIR requires that all AIR applications be digitally signed. There are two ways to do this.

2.8.2.1. Signing with a self-signed certificate

Developers can use ADT to digitally sign an AIR file with a self-signed certificate. You self-sign an AIR file by generating a self-signed certificate, and then signing the AIR file with it. Self-signing AIR files provides little security, and no way to verify that the author is who she says she is. When the application is installed, Adobe AIR will warn users that the publisher of the application cannot be verified.

NOTE

You cannot switch among certificate types when updating applications.

AIR files signed with self-signed certificates are meant primarily for development purposes. If you plan to widely distribute your application to the public, you should sign your application with a certificate issued by a respected and well-known Certification authority (CA).

2.8.2.2. Signing with a CA-issued certificate

ADT also has support for signing applications using a verified certificate from an established CA. This allows Adobe AIR to verify the publisher of the application, and to reflect this information in the installation dialog.

NOTE

You can find more information on signing AIR files, including a list of CAs that publish certificates that work with Adobe AIR, in the Adobe AIR documentation at http://www.adobe.com/go/learn_air_html.

With both types of certificates—self-signed and CA-issued—Adobe AIR can verify that the AIR file has not been tampered with.

Because we will not be redistributing the application we are creating, we will be signing our AIR file with a self-signed certificate.

2.8.3. Creating an AIR File Using ADT

Creating a self-signed AIR file requires only two steps:

Use ADT to create a self-signed certificate.
User ADT to create the AIR file, digitally signed with the self-signed certificate.

2.8.3.1. Generating a self-signed certificate

Before signing an AIR file with a self-signed certificate, we need to first generate the certificate.

We can use ADT to generate a self-signed certificate with the following command-line options:

adt -certificate -cn COMMONNAME KEYTYPE CERTFILE PASSWORD

Table 2-4 lists and explains these command-line options.

Table 2-4. ADT Signing Options
Command-line option Explanation
COMMONNAME The common name of the new certificate. This is the name associated with the certificate.
KEYTYPE The type of key to use for the certificate, either 1024-RSA or 2048-RSA.
CERTFILE The filename in which the certificate will be stored.
PASSWORD The password for the certificate.

Table 2-4. ADT Signing Options
Command-line option	Explanation
`COMMONNAME`	The common name of the new certificate. This is the name associated with the certificate.
`KEYTYPE`	The type of key to use for the certificate, either 1024-RSA or 2048-RSA.
`CERTFILE`	The filename in which the certificate will be stored.
`PASSWORD`	The password for the certificate.

To generate a self-signed certificate, follow these steps:

Open a Terminal (Mac OS X) or Console (Windows) window.
Change to the directory that contains AIRHelloWorld.html and AIRHelloWorld.xml.
Run the following command:
```
adt -certificate -cn foo 1024-RSA test_cert.p12 mypass
```
For this example, we will give the certificate a common name of "foo" with a password of "mypass".

This generates a self-signed certificate, and stores it in a file named test_cert.p12.

NOTE

You can use the same self-signed certificate to sign multiple AIR files.

At this point, you should have a file named test_cert.p12 in the same directory as your application files. You can now use this file to digitally self-sign your AIR file.

2.8.3.2. Generating an AIR file

The ADT command-line tool included in the Adobe AIR SDK is used to create AIR files. Its usage format is:

adt -package SIGNINGOPTIONS AIRFILENAME FILESTOINCLUDE

To create an AIR file that is signed with a self-signed certificate, follow these steps:

Open a Terminal (Mac OS X) or Console (Windows) window.
Change to the directory that contains AIRHelloWorld.html and AIRHelloWorld.xml.

Run the following command:

adt -package -storetype pkcs12 -keystore test_cert.p12 
AIRHelloWorld.air AIRHelloWorld.xml AIRHelloWorld.html

Upon running the command, you should be prompted for the password for the certificate. Enter the password for the certificate, which for this example is mypass.

NOTE

When signing the AIR file, ADT will attempt to connect to a timeserver on the Internet to timestamp the file. If it cannot connect to the timeserver, you will receive the following error:

Could not generate timestamp

When developing and self-signing your AIR files, you can get around this error by telling ADT to not timestamp the AIR file; you do this by adding the following option to the signing options on the command line:

-tsa none

In this case, the entire command would be:

adt -package -storetype pkcs12 -keystore test_
cert.p12 -tsa none AIRHelloWorld.air
 AIRHelloWorld.xml AIRHelloWorld.html

This should create a file named AIRHelloWorld.air in the same directory as your application files. If the file is not created, or if you receive any errors, do the following:

Make sure you have configured the SDK correctly, and that the ADT tool can be found on your system's path.
Make sure you are running the ADT command from the same directory that contains the AIRHelloWorld.xml file.
Make sure your application descriptor file contains well-formed XML.
Make sure the information in the application descriptor file is correct. Pay particular attention to the application attributes, and the content element.
Make sure the AIRHelloWorld.html, test_cert.p12, and AIRHelloWorld.xml files are in the same directory.
Make sure you entered the same password you used when generating the certificate file.

2.8.4. Testing and Installing the AIR File

Now that we have created the AIR file for our application, the only step left is to test the file and make sure it installs correctly.

Testing the AIR file requires trying to install it onto the system, and then launching it:

Switch to the directory that contains the AIR file in Windows Explorer (Windows) or the Finder (Mac OS X).
Double-click the AIR file.
Follow the instructions in the Install dialog box.
On the last screen of the Install dialog box, make sure "Start Application after installation" is checked.

The application should launch and run. If it does not launch, or if you receive an error, do the following:

Make sure you have correctly installed the 1.0 version of Adobe AIR.
Make sure there were no errors when you created the AIR file via ADT.
Make sure you have uninstalled any prerelease versions of Adobe AIR.

Once you have confirmed that the application is installed and runs correctly, you can relaunch it by clicking its icon. The default shortcut location varies, depending on your operating system. In Mac, the default shortcut is /Applications. In Windows, it is Start Menu rightwards double arrow Programs<APPLICATION NAME>.

2.8.5. Deploying the AIR File

Now that we have successfully created and packaged our AIR application, it's time to distribute it. We can distribute the AIR file via the Web, or directly via CD-ROM or other distribution mechanisms.

NOTE

You can find extensive information on how to seamlessly deploy Adobe AIR applications on the Web in the Adobe AIR documentation, as well as in the tutorial at http://www.adobe.com/devnet/air/articles/air_badge_install.html.

2.8.5.1. Setting the MIME type

One thing to watch out for when distributing AIR files for download from a web server is that the MIME type is set correctly on the server. If the MIME type is not set correctly, web browsers may treat the AIR file as a ZIP file (and may rename it in the process), or may display the raw bytes of the AIR file in the browser, instead of downloading it to the user's system.

The correct MIME type for an AIR file is:

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

For example, to set the MIME type for the Apache server, you would add the following line to your Apache configuration file:

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

Check the documentation for your web server for specific instructions on how to set the MIME type.

At this point, you have all of the basic knowledge of how to develop, test, and deploy AIR applications. You should now be ready to begin to learn more about the AIR APIs and how to build more full-featured and advanced applications.