Setting AIR application properties



Aside from all the files and other assets that make up an AIR application, each AIR application requires an application descriptor file. The application descriptor file is an XML file which defines the basic properties of the application.

When you use Adobe® Flex™ Builder™ 3, the application descriptor file is automatically generated when you create an Adobe® AIR® project. If you're developing AIR applications using the Adobe® Flex™ 3 or AIR® SDKs, you must create this file manually. A sample descriptor file, descriptor-sample.xml, can be found in the samples directory of your SDK installation.

The application descriptor file structure

The application descriptor file contains properties that affect the entire application, such as its name, version, copyright, and so on. Any filename can be used for the application descriptor file. When you package the application with either Flex Builder or ADT, the application descriptor file is renamed application.xml and placed within a special directory inside the package.

Here's an example application descriptor file:

<?xml version="1.0" encoding="utf-8" ?> 
<application xmlns="http://ns.adobe.com/air/application/1.5"> 
    <id>HelloWorld</id> 
    <version>2.0</version> 
    <filename>Hello World</filename> 
    <name>Example Co. AIR Hello World</name> 
     <description> 
        <text xml:lang="en">This is a example.</text> 
        <text xml:lang="fr">C'est un exemple.</text> 
        <text xml:lang="es">Esto es un ejemplo.</text> 
    </description> 
    <copyright>Copyright (c) 2006 Example Co.</copyright> 
    <initialWindow> 
        <title>Hello World</title> 
        <content> 
            HelloWorld-debug.swf 
        </content> 
        <systemChrome>none</systemChrome> 
        <transparent>true</transparent> 
        <visible>true</visible> 
        <minimizable>true</minimizable> 
        <maximizable>false</maximizable> 
        <resizable>false</resizable> 
        <width>640</width> 
        <height>480</height> 
        <minSize>320 240</minSize> 
        <maxSize>1280 960</maxSize> 
    </initialWindow>  
    <installFolder>Example Co/Hello World</installFolder> 
    <programMenuFolder>Example Co</programMenuFolder> 
    <icon> 
        <image16x16>icons/smallIcon.png</image16x16> 
        <image32x32>icons/mediumIcon.png</image32x32> 
        <image48x48>icons/bigIcon.png</image48x48> 
        <image128x128>icons/biggestIcon.png</image128x128>  
    </icon> 
    <customUpdateUI>true</customUpdateUI> 
    <allowBrowserInvocation>false</allowBrowserInvocation> 
    <fileTypes> 
        <fileType> 
            <name>adobe.VideoFile</name> 
            <extension>avf</extension> 
            <description>Adobe Video File</description> 
            <contentType>application/vnd.adobe.video-file</contentType> 
            <icon> 
                <image16x16>icons/avfIcon_16.png</image16x16> 
                <image32x32>icons/avfIcon_32.png</image32x32> 
                <image48x48>icons/avfIcon_48.png</image48x48> 
                <image128x128>icons/avfIcon_128.png</image128x128> 
            </icon> 
        </fileType> 
    </fileTypes> 
</application>

Defining properties in the application descriptor file

Use the XML elements and attributes in the application descriptor to define the following types of properties for your AIR application:

  • Required AIR runtime version

  • Application identity

  • Installation and program menu folders

  • Initial content and window properties

  • Application icon files

  • Whether your application provides a custom update UI

  • Whether your application can be invoked by SWF content running in the user’s browser

  • File type associations

Specifying the required AIR version

The attributes of the root element of an application descriptor file, application, specifies the required AIR runtime version:

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

xmlns The AIR namespace, which you must define as the default XML namespace. The namespace changes with each major release of AIR. The last segment of the namespace, such as “1.5.3” indicates the runtime version required by the application. Be sure to set the namespace to AIR 1.5.3 ("http://ns.adobe.com/air/application/1.5.3") if your application uses any new AIR 1.5.3 features.

For SWF-based applications, the AIR runtime version specified in the application descriptor determines the maximum SWF version that can be loaded as the initial content of the application. Applications that specify AIR 1.0 or AIR 1.1 can only use SWF9 (Flash Player 9) files as initial content — even when run using the AIR 1.5 runtime. Applications that specify AIR 1.5, or higher, can use either SWF9 or SWF10 (Flash Player 10) files as initial content. The SWF version determines which version of the AIR and Flash Player APIs are available. If a SWF9 file is used as the initial content of an AIR 1.5 application, that application will only have access to the AIR 1.1 and Flash Player 9 APIs. Furthermore, behavior changes made to existing APIs in AIR 1.5 or Flash Player 10 will not be effective. (Important security-related changes to APIs are an exception to this principle and can be applied retroactively in present or future patches of the runtime.)

For HTML-based applications, the runtime version specified in the application descriptor alone determines which version of the AIR and Flash Player APIs are available to the application. The HTML, CSS, and JavaScript behaviors are always determined by the version of Webkit used in the installed AIR runtime, not by the application descriptor.

When an AIR application loads SWF content, the version of the AIR and Flash Player APIs available to that content depends on how the content is loaded. The following table shows how the API version is determined based on the loading method:

How the content is loaded

How the API version is determined

Initial content, SWF-based application

SWF version of the loaded file

Initial content, HTML-based application

Application descriptor namespace

SWF loaded by SWF content

Version of the loading content

SWF library loaded by HTML content using <script> tag

Application descriptor namespace

SWF loaded by HTML content using AIR or Flash Player APIs (such as flash.display.Loader)

Application descriptor namespace

SWF loaded by HTML content using <object> or <embed> tags (or the equivalent JavaScript APIs)

SWF version of the loaded file

When loading a SWF file of a different version than the loading content, you can run into the two problems:

  • Loading SWF10 content by SWF9 (or earlier) — References to AIR 1.5 and Flash Player 10 APIs in the loaded content will be unresolved

  • Loading SWF9 (or earlier) content by SWF10 — APIs changed in AIR 1.5 and Flash Player 10 may behave in ways that the loaded content does not expect.

minimumPatchLevel Deprecated — do not use.

Defining the application identity

The following elements define the id, publisherID, version, name, filename, description, and copyright information:

<id>TestApp</id> 
<publisherID>48B5E02D9FB21E6389F73B8D17023320485DF8CE.1</publisherID> 
<version>2.0</version> 
<filename>TestApp</filename> 
<name> 
    <text xml:lang="en">Hello AIR</text> 
    <text xml:lang="fr">Bonjour AIR</text> 
    <text xml:lang="es">Hola AIR</text> 
</name> 
<description>An MP3 player.</description> 
<copyright>Copyright (c) 2008 YourCompany, Inc.</copyright>

id An identifier string for the application, known as the application ID. The attribute value is restricted to the following characters:

  • 0–9

  • a–z

  • A–Z

  • . (dot)

  • - (hyphen)

The value must contain 1 to 212 characters. This element is required.

The id string uniquely identifies the application.

publisherID (Optional) Specifies the publisher ID to use when creating an update for an application published with AIR 1.5.2, or earlier. If the application to be updated has no publisher ID, omit the publisherID tag.

In order for an AIR file to update an existing version of an application, the application and publisher IDs of both the installed version and the update version must match. If the IDs are not the same, the user must uninstall the earlier version before they can install the new version.

Set this value to the existing publisher ID when publishing an update for an AIR application published for AIR 1.5.2 or earlier — or which targets AIR 1.5.2, or earlier, in the application descriptor namespace. The publisher ID for such applications is computed from the code signing certificate. You can find the ID value in the META-INF/AIR/publisherid file inside the installation directory of an application.

Publisher IDs are no longer computed or assigned automatically as of AIR 1.5.3. New applications do not need and should not specify a publisher ID.

The publisher ID tag was added in AIR 1.5.3. For more information about publisher IDs, see About AIR publisher identifiers.

version Specifies the version information for the application. (It has no relation to the version of the runtime). The version string is an application-defined designator. AIR does not interpret the version string in any way. Thus, version “3.0” is not assumed to be more current than version “2.0.” Examples: "1.0", ".4", "0.5", "4.9", "1.3.4a". This element is required.

filename The string to use as a filename of the application (without extension) when the application is installed. The application file launches the AIR application in the runtime. If no name value is provided, the filename is also used as the name of the installation folder. This element is required.

The filename property can contain any Unicode (UTF-8) character except the following, which are prohibited from use as filenames on various file systems:

Character

Hexadecimal Code

various

0x00 – x1F

*

x2A

"

x22

:

x3A

>

x3C

<

x3E

?

x3F

\

x5C

|

x7C

The filename value cannot end in a period.

name (Optional, but recommended) The title displayed by the AIR application installer.

If you specify a single text node (instead of multiple text elements), the AIR application installer uses this name, regardless of the system language:

<name>Test Application</name> 

The AIR 1.0 application descriptor schema allows only one simple text node to be defined for the name (not multiple text elements).

In AIR 1.1 (or above), you can specify multiple languages in the name element. For example, the following specifies the name in three languages (English, French, and Spanish):

<name> 
    <text xml:lang="en">Hello AIR</text> 
    <text xml:lang="fr">Bonjour AIR</text> 
    <text xml:lang="es">Hola AIR</text> 
</name> 

The xml:lang attribute for each text element specifies a language code, as defined in RFC4646 (http://www.ietf.org/rfc/rfc4646.txt).

The AIR application installer uses the name that most closely matches the user interface language of the user’s operating system. For example, consider an installation in which the name element of the application descriptor file includes a value for the en (English) locale. The AIR application installer uses the en name if the operating system identifies en (English) as the user interface language. It also uses the en name if the system user interface language is en-US (U.S. English). However, if the user interface language is en-US and the application descriptor file defines both en-US and en-GB names, then the AIR application installer uses the en-US value. If the application defines no name that matches the system user interface languages, the AIR application installer uses the first name value defined in the application descriptor file.

If no name element is specified, the AIR application installer displays the filename as the application name.

The name element only defines the application title used in the AIR application installer. The AIR application installer supports multiple languages: Traditional Chinese, Simplified Chinese, Czech, Dutch, English, French, German, Italian, Japanese, Korean, Polish, Brazilian Portuguese, Russian, Spanish, Swedish, and Turkish. The AIR application installer selects its displayed language (for text other than the application title and description) based on the system user interface language. This language selection is independent of the settings in the application descriptor file.

The name element does not define the locales available for the running, installed application. For details on developing multi-language applications, see Localizing AIR applications.

description (Optional) The description of the application, displayed in the AIR application installer.

If you specify a single text node (not multiple text elements), the AIR application installer uses this description, regardless of the system language:

<description>This is a sample AIR application.</description> 

The AIR 1.0 application descriptor schema allows only one simple text node to be defined for the name (not multiple text elements).

In AIR 1.1 (or above), you can specify multiple languages in the description element. For example, the following specifies a description in three languages (English, French, and Spanish):

<description> 
    <text xml:lang="en">This is a example.</text> 
    <text xml:lang="fr">C'est un exemple.</text> 
    <text xml:lang="es">Esto es un ejemplo.</text> 
</description> 

The xml:lang attribute for each text element specifies a language code, as defined in RFC4646 (http://www.ietf.org/rfc/rfc4646.txt).

The AIR application installer uses the description that most closely matches the user interface language of the user’s operating system. For example, consider an installation in which the description element of the application descriptor file includes a value the en (English) locale. The AIR application installer uses the en name if the user’s system identifies en (English) as the user interface language. It also uses the en name if the system user interface language is en-US (U.S. English). However, if system user interface language is en-US and the application descriptor file defines both en-US and en-GB names, then the AIR application installer uses the en-US value. If the application defines no name that matches the system user interface language, the AIR application installer uses the first description value defined in the application descriptor file.

For more information on developing multi-language applications, see Localizing AIR applications.

copyright (Optional) The copyright information for the AIR application. On Mac OS, the copyright text appears in the About dialog box for the installed application. On Mac OS, the copyright information is also used in the NSHumanReadableCopyright field in the Info.plist file for the application.

Defining the installation folder and program menu folder

The installation and program menu folders are defined with the following property settings:

<installFolder>Acme</installFolder> 
<programMenuFolder>Acme/Applications</programMenuFolder>

installFolder (Optional) Identifies the subdirectory of the default installation directory.

On Windows, the default installation subdirectory is the Program Files directory. On Mac OS, it is the /Applications directory. On Linux, it is /opt/. For example, if the installFolder property is set to "Acme" and an application is named "ExampleApp", then the application is installed in C:\Program Files\Acme\ExampleApp on Windows, in /Applications/Acme/Example.app on MacOS, and /opt/Acme/ExampleApp on Linux.

Use the forward-slash (/) character as the directory separator character if you want to specify a nested subdirectory, as in the following:

<installFolder>Acme/Power Tools</installFolder>

The installFolder property can contain any Unicode (UTF-8) character except those that are prohibited from use as folder names on various file systems (see the filename property above for the list of exceptions).

The installFolder property is optional. If you specify no installFolder property, the application is installed in a subdirectory of the default installation directory, based on the name property.

programMenuFolder (Optional) Identifies the location in which to place shortcuts to the application in the All Programs menu of the Windows operating system or in the Applications menu on Linux. (This setting is currently ignored on other operating systems.) The restrictions on the characters that are allowed in the value of the property are the same as those for the installFolder property. Do not use a forward slash (/) character as the last character of this value.

Defining the properties of the initial application window

When an AIR application is loaded, the runtime uses the values in the initialWindow element to create the initial window for the application. The runtime then loads the SWF or HTML file specified in the content element into the window.

Here is an example of the initialWindow element:

<initialWindow> 
    <content>AIRTunes.swf</content> 
    <title>AIR Tunes</title> 
    <systemChrome>none</systemChrome> 
    <transparent>true</transparent> 
    <visible>true</visible> 
    <minimizable>true</minimizable> 
    <maximizable>true</maximizable> 
    <resizable>true</resizable> 
    <width>400</width> 
    <height>600</height> 
    <x>150</x> 
    <y>150</y> 
    <minSize>300 300</minSize> 
    <maxSize>800 800</maxSize> 
</initialWindow>

The child elements of the initialWindow element set the properties of the window into which the root content file is loaded.

content The value specified for the content element is the URL for the main content file of the application. This may be either a SWF file or an HTML file. The URL is specified relative to the root of the application installation folder. (When running an AIR application with ADL, the URL is relative to the folder containing the application descriptor file. You can use the root-dir parameter of ADL to specify a different root directory.)

Note: Because the value of the content element is treated as a URL, characters in the name of the content file must be URL encoded according to the rules defined in RFC 1738. Space characters, for example, must be encoded as %20.

title (Optional) The window title.

systemChrome (Optional) If you set this attribute to standard, the standard system chrome supplied by the operating system is displayed. If you set it to none, no system chrome is displayed. When using the Flex mx:WindowedApplication component, the component applies its custom chrome if standard system chrome is not set. The system chrome setting cannot be changed at run time.

transparent (Optional) Set to "true" if you want the application window to support alpha blending. A window with transparency may draw more slowly and require more memory. The transparent setting cannot be changed at run time.

Important: You can only set transparent to true when systemChrome is none.

visible (Optional) The default value is false. Set to true only if you want the main window to be visible as soon as it is created—which will also reveal changes to the window as the window components are positioned. The Flex mx:WindowedApplication component automatically displays and activates the window immediately before the applicationComplete event is dispatched, unless the visible attribute is set to false in the MXML definition.

You may want to leave the main window hidden initially, so that changes to the window’s position, the window’s size, and the layout of its contents are not shown. You can then display the window by calling the activate() method of the window or by setting the visible property to true. For details, see Working with native windows.

x, y, width, height (Optional) The initial bounds of the main window of the application. If you do not set these values, the window size is determined by the settings in the root SWF file or, in the case of HTML, by the operating system. The maximum values for width and height are each 2880.

minSize, maxSize (Optional) The minimum and maximum sizes of the window. If you do not set these values, they are determined by the operating system.

minimizable, maximizable, resizable (Optional) Specifies whether the window can be minimized, maximized, and resized. By default, these settings default to true.

Note: On operating systems, such as Mac OS X, for which maximizing windows is a resizing operation, both maximizable and resizable must be set to false to prevent the window from being zoomed or resized.

Specifying icon files

The icon property specifies one or more icon files to be used for the application. Including an icon is optional. If you do not specify an icon property, the operating system displays a default icon.

The path specified is relative to the application root directory. Icon files must be in the PNG format. You can specify all of the following icon sizes:

<icon> 
    <image16x16>icons/smallIcon.png</image16x16> 
    <image32x32>icons/mediumIcon.png</image32x32> 
    <image48x48>icons/bigIcon.png</image48x48> 
    <image128x128>icons/biggestIcon.png</image128x128>  
</icon>

If an element for a given size is present, the image in the file must be exactly the size specified. If all sizes are not provided, the closest size is scaled to fit for a given use of the icon by the operating system.

Note: The icons specified are not automatically added to the AIR package. The icon files must be included in their correct relative locations when the application is packaged.

For best results, provide an image for each of the available sizes. In addition, make sure that the icons look presentable in both 16- and 32-bit color modes.

Providing a custom user interface for application updates

AIR installs and updates applications using the default installation dialogs. However, you can provide your own user interface for updating an application. To indicate that your application should handle the update process itself, set the customUpdateUI element to true:

<customUpdateUI>true</customUpdateUI>

When the installed version of your application has the customUpdateUI element set to true and the user then double-clicks the AIR file for a new version or installs an update of the application using the seamless install feature, the runtime opens the installed version of the application, rather than the default AIR application installer. Your application logic can then determine how to proceed with the update operation. (The update AIR file must be signed with the same certificate as the installed application for an upgrade to proceed.)

Note: The customUpdateUI mechanism only comes into play when the application is already installed and the user double-clicks the AIR installation file containing an update or installs an update of the application using the seamless install feature. You can download and start an update through your own application logic, displaying your custom UI as necessary, whether or not customUpdateUI is true.

For more information, see Updating AIR applications.

Allowing browser invocation of the application

If you specify the following setting, the installed AIR application can be launched via the browser invocation feature (by the user clicking a link in a page in a web browser):

<allowBrowserInvocation>true</allowBrowserInvocation>

The default value is false.

If you set this value to true, be sure to consider security implications, described in Browser invocation.

For more information, see Installing and running AIR applications from a web page.

Declaring file type associations

The fileTypes element allows you to declare the file types with which an AIR application can be associated. When an AIR application is installed, any declared file type is registered with the operating system and, if these file types are not already associated with another application, they are associated with the AIR application. To override an existing association between a file type and another application, use the NativeApplication.setAsDefaultApplication() method at run time (preferably with the user’s permission).

Note: The runtime methods can only manage associations for the file types declared in the application descriptor.
<fileTypes> 
    <fileType> 
        <name>adobe.VideoFile</name> 
        <extension>avf</extension> 
        <description>Adobe Video File</description> 
        <contentType>application/vnd.adobe.video-file</contentType> 
        <icon> 
            <image16x16>icons/AIRApp_16.png</image16x16>       
            <image32x32>icons/AIRApp_32.png</image32x32>       
            <image48x48>icons/AIRApp_48.png</image48x48>      
            <image128x128>icons/AIRApp_128.png</image128x128> 
        </icon> 
    </fileType> 
</fileTypes>

The fileTypes element is optional. It may contain any number of fileType elements.

The name and extension elements are required for each fileType declaration that you include. The same name can be used for multiple extensions. The extension uniquely identifies the file type. (Note that the extension is specified without the preceding period.) The description element is optional and is displayed to the user by the operating system user interface. The contentType is required in AIR 1.5 (it was optional in AIR 1.0 and 1.1). The property helps the operating system to locate the best application to open a file under some circumstances. The value should be the MIME type of the file content. Note that the value is ignored on Linux if the file type is already registered and has an assigned MIME type.

Icons can be specified for the file extension, using the same format as the application icon element. The icon files must also be included in the AIR installation file (they are not packaged automatically).

When a file type is associated with an AIR application, the application will be invoked whenever a user opens a file of that type. If the application is already running, AIR will dispatch the InvokeEvent object to the running instance. Otherwise, AIR will launch the application first. In both cases, the path to the file can be retrieved from the InvokeEvent object dispatched by the NativeApplication object. You can use this path to open the file.

For more information, see Managing file associations and Capturing command line arguments.