Creating your first HTML-based AIR application with the AIR SDK
For a quick, hands-on illustration of how Adobe® AIR® works,
use these instructions to create and package a simple HTML-based
AIR “Hello World” application.
To begin, you must have installed the runtime and set up the
AIR SDK. You will use the AIR Debug Launcher (ADL) and the AIR Developer Tool (ADT)
in this tutorial. ADL and ADT are command-line utility programs
and can be found in the bin directory of the AIR
SDK (see Installing the AIR SDK). This tutorial assumes that you are already
familiar with running programs from the command line and know how
to set up the necessary path environment variables for your operating system.
Note: HTML-based AIR applications can only be developed for the
desktop and the extendedDesktop profiles. The mobile profile is
Create the project files
Every HTML-based AIR project must contain the following
two files: an application descriptor file, which specifies the application
metadata, and a top-level HTML page. In addition to these required
that defines convenient alias variables for the AIR API classes.
Create a directory named HelloWorld to
contain the project files.
Create an XML file, named HelloWorld-app.xml.
Create an HTML file named HelloWorld.html.
Copy AIRAliases.js from the frameworks folder
of the AIR SDK to the project directory.
Create the AIR application descriptor file
To begin building your AIR application, create an XML application
descriptor file with the following structure:
Open the HelloWorld-app.xml for editing.
Add the root <application> element,
including the AIR namespace attribute:
<application xmlns="http://ns.adobe.com/air/application/2.7"> The
last segment of the namespace, “2.7”, specifies the version of the
runtime required by the application.
Add the <id> element:
application ID uniquely identifies your application along with the
publisher ID (which AIR derives from the certificate used to sign
the application package). The application ID is used for installation,
access to the private application file-system storage directory, access
to private encrypted storage, and interapplication communication.
Add the <versionNumber> element:
users to determine which version of your application they are installing.
you are using AIR 2, or earlier, you must use the <version> element instead
of the <versionNumber> element.
Add the <filename> element:
name used for the application executable, install directory, and
other references to the application in the operating system.
Add the <initialWindow> element containing
the following child elements to specify the properties for your
initial application window:
the root HTML file for AIR to load.
the window visible immediately.
the window width (in pixels).
the window height.
Save the file. The completed application descriptor file
should look like the following:
<?xml version="1.0" encoding="UTF-8"?>
This example only sets a few of the possible application properties.
For the full set of application properties, which allow you to specify
such things as window chrome, window size, transparency, default
installation directory, associated file types, and application icons,
see AIR application descriptor files.
Create the application HTML page
You now need to create a simple HTML page to serve as the
main file for the AIR application.
Open the HelloWorld.html file for editing.
Add the following HTML code:
In the <head> section of the HTML,
import the AIRAliases.js file:
defines a property named runtime on the HTML window
object. The runtime property provides access to the built-in AIR
classes, using the fully qualified package name of the class. For
example, to create an AIR File object you could add the following
var textFile = new runtime.flash.filesystem.File("app:/textfile.txt");
The AIRAliases.js file
defines convenient aliases for the most useful AIR APIs. Using AIRAliases.js,
you could shorten the reference to the File class to the following:
var textFile = new air.File("app:/textfile.txt");
Below the AIRAliases script tag, add another script tag containing
The appLoad() function
simply calls the air.trace() function. The trace message
print to the command console when you run the application using ADL.
Trace statements can be very useful for debugging.
Save the file.
Your HelloWorld.html file should now look like
Test the application
To run and test the application from the command line,
use the AIR Debug Launcher (ADL) utility. The ADL executable can
be found in the bin directory of the AIR SDK. If
you haven’t already set up the AIR SDK, see Installing the AIR SDK.
Open a command console or shell. Change to the directory
you created for this project.
Run the following command:
AIR window opens, displaying your application. Also, the console
window displays the message resulting from the air.trace() call.
more information, see AIR application descriptor files.
Create the AIR installation file
When your application runs successfully, you can use the
ADT utility to package the application into an AIR installation
file. An AIR installation file is an archive file that contains
all the application files, which you can distribute to your users.
You must install Adobe AIR before installing a packaged AIR file.
To ensure application security, all AIR installation files must
be digitally signed. For development purposes, you can generate
a basic, self-signed certificate with ADT or another certificate
generation tool. You can also buy a commercial code-signing certificate
from a commercial certificate authority such as VeriSign or Thawte.
When users install a self-signed AIR file, the publisher is displayed
as “unknown” during the installation process. This is because a
self-signed certificate only guarantees that the AIR file has not
been changed since it was created. There is nothing to prevent someone
from self-signing a masquerade AIR file and presenting it as your
application. For publicly released AIR files, a verifiable, commercial
certificate is strongly recommended. For an overview of AIR security issues,
see AIR security (for ActionScript developers)
or AIR security (for HTML developers).
Generate a self-signed certificate and key pair
command prompt, enter the following command (the ADT executable
is located in the bin
directory of the AIR SDK):
adt -certificate -cn SelfSigned 1024-RSA sampleCert.pfx samplePassword
generates a keystore file named sampleCert.pfx containing
a certificate and the related private key.
This example uses
the minimum number of attributes that can be set for a certificate.
The key type must be either 1024-RSA or 2048-RSA (see Signing AIR applications).
Create the AIR installation file
From the command prompt,
enter the following command (on a single line):
adt -package -storetype pkcs12 -keystore sampleCert.pfx HelloWorld.air
HelloWorld-app.xml HelloWorld.html AIRAliases.js
will be prompted for the keystore file password.
argument is the AIR file that ADT produces. HelloWorld-app.xml is
the application descriptor file. The subsequent arguments are the files
used by your application. This example only uses two files, but
you can include any number of files and directories. ADT verifies
that the main content file, HelloWorld.html is included in the package,
but if you forget to include AIRAliases.js, then your application
simply won’t work.
After the AIR package is created, you can
install and run the application by double-clicking the package file.
You can also type the AIR filename as a command in a shell or command
same as it would in a typical web browser. (In fact, AIR uses the
same WebKit rendering engine used by the Safari web browser.) However,
there are some important differences that you must understand when
you develop HTML applications in AIR. For more information on these