Common settings

Several application descriptor settings are important for all mobile device applications.

Required AIR runtime version

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

Note: (AIR 3.7 and higher) By default, ADT packages the runtime with Android applications.

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">
Note: Support for iOS 3 devices is provided by the Packager for iPhone SDK, based on the AIR 2.0 SDK. For information about building AIR applications for iOS 3, see Building iPhone apps. The AIR 2.6 SDK (and later) support iOS 4, and above on iPhone 3Gs, iPhone 4, and iPad devices.

Application identity

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

Android application IDs

On Android, the ID is converted to the Android package name by prefixing “air.” to the AIR ID. Thus, if your AIR ID is com.example.MyApp, then the Android package name is air.com.example.MyApp.

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

In addition, if the ID is not a legal package name on the Android operating system, it is converted to a legal name. Hyphen characters are changed to underscores and leading digits in any ID component are preceded by a capital “A”. For example, the ID: 3-goats.1-boat, is transformed to the package name: air.A3_goats.A1_boat.

Note: The prefix added to the application ID can be used to identify AIR applications in the Android Market. If you do not want your application to identified as an AIR application because of the prefix, you must unpackage the APK file, change the application ID, and repackage it as described in, Opt-out of AIR application analytics for Android.

iOS application IDs

Set the AIR application ID to match the app ID you created in the Apple iOS Provisioning Portal.

iOS App IDs contain a bundle seed ID followed by a bundle identifier. The bundle seed ID is a string of characters, such as 5RM86Z4DJM, that Apple assigns to the App ID. The bundle identifier contains a reverse-domain-style name that you pick. The bundle identifier can end in an asterisk (*), indicating a wildcard app ID. If the bundle identifier ends in the wildcard character, you can replace that wildcard with any legal string.

For example:

  • If your Apple app ID is, 5RM86Z4DJM.com.example.helloWorld, you must use com.example.helloWorld in the application descriptor.

  • If your Apple app ID is 96LPVWEASL.com.example.* (a wildcard app ID), then you could use com.example.helloWorld, or com.example.anotherApp, or some other ID that starts with com.example.

  • Finally, if your Apple app ID is just the bundle seed ID and a wildcard, such as: 38JE93KJL.*, then you can use any application ID in AIR.

When specifying the app ID, do not include the bundle seed ID portion of the app ID.

Application version

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.

Main application SWF

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.

Main screen properties

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.

Supported profiles

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>

Required native extensions

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.

Virtual keyboard behavior

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>
Since pan is the default value, omitting the softKeyboardBehavior element also enables the automatic keyboard behavior.
Note: When you also use GPU rendering, the pan behavior is not supported.