Common settings

Specify the version of the AIR runtime required by your application using the namespace of the application descriptor file.

The namespace, assigned in the application element, determines, in large part, which features your application can use. For example, if your application uses the AIR 2.7 namespace, and the user has some future version installed, then your application will still see the AIR 2.7 behavior (even if the behavior has been changed in the future version). Only when you change the namespace and publish an update will your application have access to the new behavior and features. Security fixes are an important exception to this rule.

On devices that use a runtime separate from the application, such as Android on AIR 3.6 and earlier, the user will be prompted to install or upgrade AIR if they do not have the required version. On devices that incorporate the runtime, such as iPhone, this situation does not occur (since the required version is packaged with the app in the first place).

Specify the namespace using the xmlns attribute of the root application element. The following namespaces should be used for mobile applications (depending on which mobile platform you are targeting):

iOS 4+ and iPhone 3Gs+ or Android: 
<application xmlns="http://ns.adobe.com/air/application/2.7"> 
iOS only: 
<application xmlns="http://ns.adobe.com/air/application/2.0">

Several settings should be unique for each application that you publish. These include the ID, the name, and the filename.

<id>com.example.MyApp</id> 
<name>My Application</name> 
<filename>MyApplication</filename>

In AIR 2.5 and later, specify the application version in the versionNumber element. The version element can no longer be used. When specifying a value for versionNumber, you must use a sequence of up to three numbers separated by dots, such as: “0.1.2”. Each segment of the version number can have up to three digits. (In other words, “999.999.999” is the largest version number permitted.) You do not have to include all three segments in the number; “1” and “1.0” are legal version numbers as well.

You can also specify a label for the version using the versionLabel element. When you add a version label it is displayed instead of the version number in such places as the Android Application info screen. A version label must be specified for apps that are distributed using the Android Market. If you do not specify a versionLabel value in the AIR application descriptor, then the versionNumber value is assigned to the Android version label field.

<!-- AIR 2.5 and later --> 
<versionNumber>1.23.7<versionNumber> 
<versionLabel>1.23 Beta 7</versionLabel>

On Android, the AIR versionNumber is translated to the Android integer versionCode using the formula: a*1000000 + b*1000 + c, where a, b, and c are the components of the AIR version number: a.b.c.

Specify the main application SWF file in the content child of the initialWindow element. When you target devices in the mobile profile, you must use a SWF file (HTML-based applications are not supported).

<initialWindow> 
    <content>MyApplication.swf</content> 
</initialWindow>

You must include the file in the AIR package (using ADT or your IDE). Simply referencing the name in the application descriptor does not cause the file to be included in the package automatically.

Several child elements of the initialWindow element control the initial appearance and behavior of the main application screen.

• aspectRatio — Specifies whether the application should initially display in a portrait format (height greater than width), a landscape format (height less than width), or any format (the stage automatically orients to all orientations).

  <aspectRatio>landscape</aspectRatio>

• autoOrients — Specifies whether the stage should automatically change orientation as the user rotates the device or performs another orientation-related gesture such as opening or closing a sliding keyboard. If false, which is the default, then the stage will not change orientation with the device.

  <autoOrients>true</autoOrients>

• depthAndStencil — Specifies to use the depth or stencil buffer. You typically use these buffers when working with 3D content.

  <depthAndStencil>true</depthAndStencil>

• fullScreen — Specifies whether the application should take up the full device display, or should share the display with the normal operating system chrome, such as a system status bar.

  <fullScreen>true</fullScreen>

• renderMode — Specifies whether the runtime should render the application with the graphics processing unit (GPU) or the main, central processing unit (CPU). In general, GPU rendering will increase rendering speed, but some features, such as certain blend modes and PixelBender filters, are unavailable in GPU mode. In addition, different devices, and different device drivers, have varying GPU capabilities and limitations. You should always test your application on the widest variety of devices possible, especially when using GPU mode.

  You can set the render mode to gpu, cpu, direct, or auto. The default value is auto, which currently falls back to cpu mode.

  Note: In order to leverage GPU acceleration of Flash content with AIR for mobile platforms, Adobe recommends that you use renderMode="direct" (that is, Stage3D) rather than renderMode="gpu". Adobe officially supports and recommends the following Stage3D based frameworks: Starling (2D) and Away3D (3D). For more details on Stage3D and Starling/Away3D, see http://gaming.adobe.com/getstarted/.

  <renderMode>direct</renderMode>

  Note: You cannot use renderMode=”direct” for applications that run in the background.

  The limitations of GPU mode are:

  • The Flex framework does not support the GPU rendering mode.

  • Filters are not supported

  • PixelBender blends, and fills are not supported

  • The following blend modes are not supported: layer, alpha, erase, overlay, hardlight, lighten, and darken

  • Using GPU rendering mode in an app that plays video is not recommended.

  • In GPU rendering mode, text fields are not properly moved to a visible location when the virtual keyboard opens. To ensure that your text field is visible while the user enters text use the softKeyboardRect property of the stage and soft keyboard events to move the text field to the visible area.

  • If a display object cannot be rendered by the GPU, it is not displayed at all. For example, if a filter is applied to a display object, the object is not shown.

  Note: The GPU implementation for iOS in AIR 2.6+ is much different than the implementation used in the earlier, AIR 2.0 version. Different optimization considerations apply.

You can add the supportedProfiles element to specify which device profiles your application supports. Use the mobileDevice profile for mobile devices. When you run your application with the Adobe Debug Launcher (ADL), ADL uses the first profile in the list as the active profile. You can also use the -profile flag when running ADL to select a particular profile in the supported list. If your application runs under all profiles, you can leave the supportedProfiles element out altogether. ADL uses the desktop profile as the default active profile in this case.

To specify that your application supports both the mobile device and desktop profiles, and you normally want to test the app in the mobile profile, add the following element:

<supportedProfiles>mobileDevice desktop</supportedProfiles>

Applications that support the mobileDevice profile can use native extensions.

Declare all native extensions that the AIR application uses in the application descriptor. The following example illustrates the syntax for specifying two required native extensions:

<extensions> 
     <extensionID>com.example.extendedFeature</extensionID> 
    <extensionID>com.example.anotherFeature</extensionID> 
</extensions>

The extensionID element has the same value as the id element in the extension descriptor file. The extension descriptor file is an XML file called extension.xml. It is packaged in the ANE file you receive from the native extension developer.

Set the softKeyboardBehavior element to none in order to disable the automatic panning and resizing behavior that the runtime uses to make sure that the focused text entry field is in view after the virtual keyboard is raised. If you disable the automatic behavior, then it is your application’s responsibility to make sure that the text entry area, or other relevant content is visible after the keyboard is raised. You can use the softKeyboardRect property of the stage in conjunction with the SoftKeyboardEvent to detect when the keyboard opens and determine the area it obscures.

To enable the automatic behavior, set the element value to pan:

<softKeyboardBehavior>pan</softKeyboardBehavior>