2. Getting Started with Adobe AIR Development

What Do You Need to Develop Adobe AIR Applications?

You need a number of items to begin developing AIR applications.

Adobe AIR Runtime

The Adobe AIR runtime is required to test application icons and deploy AIR applications. You can download the runtime for free from http://www.adobe.com/go/getair.

Adobe AIR SDK

The Adobe AIR SDK contains command-line tools, sample files, and other resources to make it easier to develop AIR applications. In particular, we will be using the command-line tools included in the SDK (ADL and ADT), which will allow us to test, sign, and package our AIR applications from virtually any development environment.

You can download the AIR SDK for free from http://www.adobe.com/go/getairsdk.

HTML/JavaScript IDE or Editor

Building AIR applications with HTML and JavaScript requires that you have a way to create the HTML and JavaScript files. You can use any tool that supports creating and editing text files (such as VIM or Notepad), although it’s recommended that you use a tool that has richer support for working with HTML and JavaScript files, such as Adobe Dreamweaver, Panic’s Coda, or Aptana Studio.

Note

You can find more information on Adobe Dreamweaver at http://www.adobe.com/go/dreamweaver, Panic’s Coda at http://www.panic.com/coda/, and Aptana Studio at http://www.aptana.com.

Supported Operating System

Although it is possible to develop and package AIR applications on virtually any operating system (including Linux), you can test and deploy AIR applications only on operating systems supported by Adobe AIR.

The supported operating systems are:

Microsoft Windows 2000 SP4
Microsoft Windows XP SP2
Windows Vista Home Premium, Business, Ultimate, or Enterprise
Mac OS 10.4.910 and later (Intel and PowerPC)

Note

H.264 video playback on a Mac requires an Intel processor.

Adobe is also currently working on adding support for Linux.

Uninstalling Prerelease Versions of Adobe AIR

If you have installed prerelease (alpha and/or beta) versions of Adobe AIR, you may need to uninstall them before installing the 1.0 runtime. However, whether this is strictly required can be a little tricky to determine.

Table 2-1 lists the prerelease versions of Adobe AIR and whether they should be uninstalled before installing Adobe AIR 1.0.

Table 2-1. Prerelease versions of Adobe AIR

Version	Uninstall?
Alpha	Uninstall
Beta 1	Will be uninstalled automatically by the Adobe AIR 1.0 installer
Beta 2	No need to uninstall
Beta 3	No need to uninstall

As Table 2-1 shows, the beta 2 and beta 3 runtimes can run side by side with Adobe AIR 1.0. This allows you to run applications built for beta 2 and beta 3 until those betas expire.

If you do not know whether you have installed the alpha version, it is a good idea to go ahead and uninstall all prerelease versions of Adobe AIR.

Uninstalling on Windows

To uninstall all prerelease versions of Adobe AIR on Windows, follow these steps:

In the Windows Start menu, select Settings→Control Panel.
Select the Add or Remove Programs control panel.
Select the prerelease version of Adobe AIR to uninstall (depending on the version, it may be referred to by its code name of “Apollo”).
Click the Change/Remove button.

Uninstalling on Mac

Follow these steps to uninstall all prerelease versions of Adobe AIR on the Mac. Depending on the prerelease version(s) of Adobe AIR that you have installed, all steps may not apply.

Run the Adobe AIR Uninstaller in the /Users/<User>/Applications directory (where <User> is your system user account name).
Run the Adobe AIR Uninstaller in the /Applications directory.
Delete the /Library/Frameworks/Adobe Apollo.framework directory.
Delete the /Library/Receipts/Adobe Apollo.pkg file.
Empty the Trash.

Once you have done this, you are ready to install the 1.0 runtime.

Installing Adobe AIR

Although it is not necessary to have Adobe AIR installed on your computer to develop and test Adobe AIR applications, it is useful to have it to try other AIR applications and to test your final application’s deployment and packaging.

Installing the runtime is simple, and requires downloading and running the Adobe AIR Installer.

Download the AIR Installer from http://www.adobe.com/go/getair.
Launch the installer. On a Mac, you must first mount the .dmg file, which contains the installer.
Follow the installation instructions.

Note

It is also possible to install Adobe AIR directly from the runtime via express install. We will cover this in Chapter 4.

As Adobe AIR is simply a runtime and not an application that can be launched, the easiest way to confirm that it is installed correctly is to try installing an AIR application. You can do this by either downloading an AIR application and installing it, or following the instructions later in the chapter to build a simple AIR application.

Note

You can download sample AIR applications from Adobe’s web site, at http://www.adobe.com/go/air_samples.

Uninstalling Adobe AIR

The process for uninstalling Adobe AIR is different depending on your operating system.

Uninstalling on Windows

On Windows, you can uninstall Adobe AIR the same way that you uninstall any other application. Just select Adobe AIR in the Add/Remove Programs section of the Control Panel.

Uninstalling on an Mac

The Adobe AIR installer places an uninstall application on the user’s system when it is installed. To uninstall Adobe AIR, launch the uninstaller named Adobe AIR Uninstaller which you can find in the /Applications/Utilities directory.

Setting Up the Adobe AIR SDK and Command-Line Tools

The Adobe AIR SDK beta contains tools, samples, and code that make it easier to develop, test, and deploy applications. In particular, it contains two command-line tools that we will use:

ADL: You use this tool to launch and test an Adobe AIR application without having to install it first.
ADT: You use this tool to package and sign an AIR application for distribution.

Installing the Adobe AIR SDK

To ease development, you should place the path to these files within your system’s path. This will allow you to execute the tools from anywhere on your system.

The command-line tools are located in the bin directory within the SDK.

Download the Adobe AIR SDK from http://www.adobe.com/go/getairsdk.
Open the SDK:
a) On Windows, uncompress the ZIP archive.
b) On Mac, mount the .dmg file.
Copy the contents of the SDK to your system (we will refer to this location as <SDK_Path>).
Note
To run the command-line tools, you need to copy only the bin, lib, and runtime directories from the SDK.
It’s important that the bin, lib, and runtime directories within the SDK maintain their relative paths to each other.
At this point, you should have at least the following three directories: <SDK_Path>/bin, <SDK_Path>/lib, and <SDK_Path>/runtime. The ADL and ADT command-line tools are located in the bin directory.

Placing the Command-Line Tools Within the System Path

All that is left to do is to place the <SDK_Path>/bin directory into your system path so that you can execute the command-line applications from anywhere on your system.

The instructions for this are different depending on whether you are on a Mac or Windows-based system.

Windows

If you are on a Windows system, follow these steps:

Open the System Properties dialog box and click the Advanced tab. You can find this in the System settings in the Control Panel.
Click the Environment Variables button.
Select the PATH entry and then click the Edit button. Add the path to the bin directory to the end of the current variable value, separating it from previous values with a semicolon:
```
; <SDK_Path>/bin
```
Figure 2-1 Editing PATH variables in Windows.
Figure 2-1. Placing command-line tools in the system path on Windows
Click OK to close the panels.

To test the installation, open a new Windows Console (Start→Run→Console), and type adt.

Note

Make sure you open a new Console window in order to ensure the new PATH settings take affect.

You should see output similar to this:

usage:
  adt -package SIGNING_OPTIONS <air-file> <app-desc> FILE_ARGS
  adt -prepare <airi-file> <app-desc> FILE_ARGS
  adt -sign SIGNING_OPTIONS <airi-file> <air-file>
  adt -checkstore SIGNING_OPTIONS
  adt -certificate -cn <name> ( -ou <org-unit> )? 
( -o <org-name> )? ( -c <country> )?
 <key-type> <pfx-file> <password>
  adt -help

SIGNING_OPTIONS: -storetype <type> ( -keystore <store> )? 
( -storepass <pass> )? ( -keypass <pass> )? ( -providerName
 <name> )? ( -tsa <url> )?
FILE_ARGS: <fileOrDir>* (( -C <dir> <fileOrDir>+ ) | 
( -e <file> <path> ))* -C dir

This means the tools are configured correctly.

If you get an error stating that the file cannot be found, do the following:

Make sure the bin, lib, and runtime directories are included in the <SDK_Path> directory.
Make sure you included the path to the <SDK_Path> directory correctly in the PATH environment variable.
Make sure you opened a new Console window before running the command.

Mac

There are a number of ways to add the path to the AIR SDK to your system path, depending on which shell you are using and how you specify user environment variables.

The following instructions explain how to modify your PATH environment variable if you are using the bash shell:

Open the Terminal program (/Applications/Utilities/Terminal). Make sure you’re in your home directory by typing cd and pressing Enter.
Check to see whether one of two files is present. Enter the command ls -la.
Look for a file named either .profile or .bashrc.
If you have neither file, create the .profile file with the command touch .profile.
Open the .profile or .bashrc file with a text editor.
Look for a line that looks similar to this:
```
export PATH=$PATH:/usr/local/bin
```
Add the path to the <SDK_Path>/bin directory to the end of this line. For example, if <SDK_Path>/bin is at /airsdk/bin, the export path should look something like this:
```
export PATH=$PATH:/usr/local/bin;/airsdk/bin
```
Make sure you separate the entries with a colon.
If the file is empty, add the following line:
```
export PATH=$PATH:/airsdk/bin
```
Save and close the file.
Run the command source .profile to load the new settings (or .bashrc, if that is the file you edited).
Confirm that the new settings have taken effect by typing echo $PATH and pressing Enter. Make sure the <SDK_Path>/bin path is included in the output.

To test the installation, open a Terminal window and type adt.

You should see output similar to this:

usage:
  adt -package SIGNING_OPTIONS <air-file> <app-desc> 
  FILE_ARGS
  adt -prepare <airi-file> <app-desc> FILE_ARGS
  adt -sign SIGNING_OPTIONS <airi-file> <air-file>
  adt -checkstore SIGNING_OPTIONS
  adt -certificate -cn <name> ( -ou <org-unit> )? 
  ( -o <org-name> )? ( -c <country> )?
  <key-type> <pfx-file> <password>
  adt -help

SIGNING_OPTIONS: -storetype <type> ( -keystore 
<store> )? ( -storepass <pass> )? ( -keypass <pass> )? 
( -providerName <name> )? ( -tsa <url> )? FILE_ARGS: 
<fileOrDir>* (( -C <dir> <fileOrDir>+ ) | ( -e <file>
<path> ))* -C

This means the tools are configured correctly.

If you get an error stating that the file cannot be found, do the following:

Make sure the bin, lib, and runtime directories are included in the <SDK_Path> directory.
Make sure you included the path to <SDK_Path>/bin correctly in the PATH environment variable.
Make sure you either opened a new Terminal window, or ran source on your configuration file.

Creating a Simple AIR Application with HTML and JavaScript

Now that we have installed and configured Adobe AIR and the Adobe AIR SDK, we are ready to build our first AIR application.

We will build a very simple “Hello World” example. Once we have built and tested the application, our development environment will be set up and ready to build more complex and functional AIR applications.

Creating the Application Files

Every Adobe AIR application contains a minimum of two files. The first file is the root content file. This is the main HTML or SWF file for the application, and is the file that will be displayed/executed when the application first starts up.

The second file is called the application descriptor file, and it is an XML file that provides metadata to Adobe AIR about the application.

Let’s create these files for our application:

Create a new folder called AIRHelloWorld.
Inside this folder, create two new files called AIRHelloWorld.html and AIRHelloWorld.xml.
Open each file using your favorite text or HTML editor/IDE.

Understanding application descriptor files

The application descriptor file is an XML file required for each AIR application. It provides general metadata (such as the application name and description) to Adobe AIR, as well as information on how the application should be run. This includes specifying the root application file for the application and the window mode that the initial application window should use.

First, let’s look at the entire application descriptor file (AIRHelloWorld.xml) for our application, and then we will go into more detail regarding each item within the file.

Note

You can find a sample application descriptor file in the AIR SDK in the templates folder.

Open AIRHelloWorld.xml and type in the following text:

<?xml version="1.0" encoding="utf-8" ?>
<application xmlns="http://ns.adobe.com/air/application/1.0">

    <id>com.oreilly.AIRHelloWorld</id>
    <filename>AIRHelloWorld</filename>
    <name>AIR Hello World</name>
    <description>A simple AIR hello world application</
    description> <version>1.0</version>

    <initialWindow>
         <content>AIRHelloWorld.html</content>
         <title>AIR Hello World</title>
         <systemChrome>standard</systemChrome>
         <transparent>false</transparent>
         <visible>true</visible>
         <minimizable>true</minimizable>
         <maximizable>true</maximizable>
         <resizable>true</resizable>
    </initialWindow>
</application>

The content should be pretty self-explanatory, but let’s go through it line by line to understand what is going on.

<application xmlns="http://ns.adobe.com/air/application/1.0">

The namespace specifies the version of Adobe AIR that the application targets—in this case 1.0.

Lets look at the next element:

    <id>com.oreilly.AIRHelloWorld</id>

The id element is important; it specifies a unique ID for the application. Adobe AIR uses this ID to differentiate one application from another.

As you can see, it uses the reverse domain format, which you may be familiar with from some programming languages such as Java, ActionScript, and some JavaScript frameworks. You can create your own ID using your domain name and application name.

The next section of elements specify general metadata about the application:

    <filename>AIRHelloWorld</filename>
    <name>AIR Hello World</name>
    <description>A simple AIR hello world application</
    description> <version>1.0</version>

Table 2-2 lists each element and provides a description.

Table 2-2. Application Meta Data Elements

Element	Description
`filename`	The name of the native application executable that will be created.
`name`	The name of the application. This is the name that will be exposed to the operating system and user.
`description`	Optional. A human-readable description of the application that will be presented to the user during the installation process.
`version`	Required. Specifies the version of the applications (such as “1.0”, “v1”, etc.).

The next element is the initialWindow tag, which contains the elements that specify how the application should be run by the runtime:

    <initialWindow>
         <content>AIRHelloWorld.html</content>
         <title>AIR Hello World</title>
         <systemChrome>standard</systemChrome>
         <transparent>false</transparent>
         <visible>true</visible>
         <minimizable>true</minimizable>
         <maximizable>true</maximizable>
         <resizable>true</resizable>
    </initialWindow>

The content element is required and points to the main root file of the application, which in this case is an HTML file.

Note

The application descriptor file and root content file must be in the same folder.

The initialWindow element has a number of other elements that specify the initial window parameters and chrome of the application when it is first launched (see Table 2-3).

Table 2-3. initalWindow elements

Element	Description
`title`	The title that will appear in the main application window. Optional.
`systemChrome`	The type of the system chrome that the application should use (`standard` or `none`).
`transparent`	Whether the application background should be transparent. This option is applicable only if `systemChrome` is set to `none`. Optional. Default value is `false`.
`visible`	Whether the application is visible when it is first launched. This is useful if your application needs to perform some complex initialization before displaying the UI to the user. Optional. Default is `false`.
`minimizable`	Whether the application can be minimized. Optional. Default is `true`.
`maximizable`	Whether the application can be maximized. Optional. Default is `true`.
`resizable`	Whether the application can be resized. Optional. Default is `true`.

For our example, we will use the operating system’s window chrome.

Note

Notice that the default value of the visible element is false. This means that if you do not explicitly set the element to true, your application will have no UI when it launches. In this case, you will have to programmatically set the visible property to true.

This can be useful if the application needs to perform some initialization or layout when it first launches. You can allow the application to do its layout first, and then only display the UI to the user once the layout is complete.

This is all that is required for the application descriptor file for our application. At this point, we are ready to create the main HTML file for our application.

Creating the root application file

The root application file is the main file for the application that will be loaded when the application is launched. This file can be either a compiled Flash file (SWF) or an HTML file.

For this chapter, we will create a very simple HTML file to ensure that our development environment is configured correctly. We will cover more advanced AIR API usage in Chapter 3 and Chapter 4.

<html>
<head>
    <title>AIRHelloWorld</title>

    <script>
        function init()
        {
            runtime.trace("init function called");
        }
    </script>

</head>
<body onload="init()">
    <div align="center">Hello World</div>
</body>
</html>

As you can see, this is a very basic HTML file that displays “Hello World” and calls a JavaScript function once the file has loaded and initialized.

A couple of lines are worth pointing out:

<body onload="init()">

This line says we are just using the standard onload event on the body element to get an entry point for JavaScript into our application.

    <script>
        function init()
        {
            ...
        }
    </script>

This line says we are using a standard JavaScript function to capture the onload event.

Accessing Adobe AIR APIs

Looking at the init JavaScript function, you’ll see some code you may not be familiar with:

runtime.trace("init function called");

This is the only AIR-specific code/markup in the entire application. The runtime property is a property placed on the window object by Adobe AIR and provides an entry point into the Adobe AIR engine and APIs. The trace function is a top-level AIR API that takes a string and prints it out to the command line (when the application is launched via the command line).

All access to AIR-specific APIs (including Flash Player APIs) is accomplished from JavaScript via the runtime property. We will cover this in more detail throughout the rest of the book.

Note

Checking for the existence of the runtime property is a simple way to determine whether your HTML and JavaScript application is running within Adobe AIR. To check for the property, run the following code:

if(window.runtime)
{
 //running within AIR
}

Now that we have created both the application descriptor file and the root HTML application file, we are ready to run and test our application within the runtime.

Testing the Application

Although a number of HTML IDEs (such as Adobe Dreamweaver) have support for launching and testing AIR applications directly from within the IDE, we will focus on launching and testing AIR applications using the ADL command-line tool included within the SDK. This will provide a solid basis for an understanding of what is going on. It also provides the most flexibility in integrating the development process with other IDEs, editors, and workflows.

Using ADL to Launch the Application

The first step in testing the application is to run it as an AIR application to make sure that:

There are no errors in the application descriptor file
The application launches
The HTML renders correctly
The JavaScript code functions as expected

Although we could package up the entire application and then install it, this would be tedious, and it would make it difficult to quickly iterate on and test new versions. Luckily, the Adobe AIR SDK provides a command-line tool called ADL, which allows you to launch an AIR application without having to install it first.

To test the application:

Open a Terminal window (on the Mac) or a Console window (on Windows).
Change to the directory that contains the AIRHelloWorld.html and AIRHelloWorld.xml files.
Run ADL with the following command, passing in the name of the application descriptor file:
```
adl AIRHelloWorld.xml
```

This should launch your application within the standard system chrome of your operating system (see Figure 2-2).

Figure 2-2. AIRHelloWorld application running from ADL on Mac OS X

If the application does not launch correctly, or if you get an error, do the following:

Make sure you have configured the SDK correctly so that the ADL tool can be found.
Make sure you are running the ADL 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 initialWindow value.
Make sure the AIRHelloWorld.html and AIRHelloWorld.xml files are in the same directory.

Now that we have fixed any issues and our application is running correctly, we can explore how to get information from the application at runtime.

Capturing Output from the Application at Runtime

When running applications from the command line via ADL, you can get runtime information and debugging information from the application in a number of ways.

Runtime JavaScript errors

Any runtime errors that arise from JavaScript execution while an AIR application is launched via ADL is running will be output to ADL’s standard out.

Let’s modify our application to cause it to generate a JavaScript runtime error. Change the contents of AIRHelloWorld.html to the following

<html>
<head>
    <title>AIRHelloWorld</title>

    <script>
        function init()
        {
            runtime2.trace(“init function called”);
        }
    </script>

</head>
<body onload="init()">
    <div align="center">Hello World</div>
</body>
</html>

All we did was change the init function to try to access a property named runtime2 that does not exist:

runtime2.trace("init function called");

Save the file, and run the application from ADL:

adl AIRHelloWorld.xml

The application should launch, and you should see the following error output from the command line from which you launched the application:

ReferenceError: Can't find variable: runtime2
init at app:/AIRHelloWorld.html : 8
init at app:/AIRHelloWorld.html : 8
onload at app:/AIRHelloWorld.html : 13

This output provides the error, which in this case is that the variable named runtime2 cannot be found, as well as the line number on which the error occurred (8) and a stack trace of the call. You can use this information to track down any errors within your application.

There are also times when the application may not be functioning correctly, but is not throwing any errors. In such cases, it is useful to be able to capture information about the state of the application at runtime to track down any issues.

Adobe AIR provides a function to make it possible to send information from the application to standard out at runtime.

runtime.trace

As we touched on earlier in the chapter, Adobe AIR provides a mechanism for sending strings from JavaScript to the command line.

The trace function on the runtime property takes a string, which will then be output to ADL’s standard out. Here is an example of its usage:

runtime.trace("This will be sent to standard out");

This can be useful for tracking information about the state of the application without having to interrupt the execution of the program.

Any non-string objects passed to trace() will have their toString() function called. The JavaScript Object object provides a default toString() implementation, although some classes (such as Array) implement more context-sensitive toString() functions.

Here is an example of tracing an array that contains various data types:

var a = ["a", 1, {foo:"bar"}];
runtime.trace(a);

This will result in the following output on the command line from ADL:

a,1,[object Object]

Of course, you can implement your own toString() method on your custom JavaScript classes, or override toString() functions on existing classes to provide more class-specific output.

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.

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.

Digitally Signing AIR Files

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

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).

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.

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.

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.

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.

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.

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→Programs→<APPLICATION NAME>.

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.

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.

Table of Contents for 2. Getting Started with Adobe AIR Development

Create new playlist

Sign In

Sign Up

Chapter 2. Getting Started with Adobe AIR Development

What Do You Need to Develop Adobe AIR Applications?

Adobe AIR Runtime

Adobe AIR SDK

HTML/JavaScript IDE or Editor

Note

Supported Operating System

Note

Uninstalling Prerelease Versions of Adobe AIR

Uninstalling on Windows

Uninstalling on Mac

Installing Adobe AIR

Note

Note

Uninstalling Adobe AIR

Uninstalling on Windows

Uninstalling on an Mac

Setting Up the Adobe AIR SDK and Command-Line Tools

Installing the Adobe AIR SDK

Note

Placing the Command-Line Tools Within the System Path

Windows

Note

Mac

Creating a Simple AIR Application with HTML and JavaScript

Creating the Application Files

Understanding application descriptor files

Note

Note

Note

Creating the root application file

Accessing Adobe AIR APIs

Note

Testing the Application

Using ADL to Launch the Application

Capturing Output from the Application at Runtime

Runtime JavaScript errors

runtime.trace

Packaging and Deploying the AIR Application

What Is an AIR File?

Note

Digitally Signing AIR Files

Signing with a self-signed certificate

Note

Signing with a CA-issued certificate

Note

Creating an AIR File Using ADT

Generating a self-signed certificate

Note

Generating an AIR file

Note

Testing and Installing the AIR File

Deploying the AIR File

Note

Setting the MIME type

Table of Contents for
2. Getting Started with Adobe AIR Development