Setting mobile application properties

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>

AIR sets several manifest entries in the generated Android manifest document to ensure that application and runtime features work correctly. You cannot define the following settings:

The Android security model requires that each app request permission in order to use features that have security or privacy implications. These permissions must be specified when the app is packaged, and cannot be changed at runtime. The Android operating system informs the user which permissions an app is requesting when the user installs it. If a permission required for a feature is not requested, the Android operating system might throw an exception when your application access the feature, but an exception is not guaranteed. Exceptions are transmitted by the runtime to your application. In the case of a silent failure, a permission failure message is added to the Android system log.

In AIR, you specify the Android permissions inside the android element of the application descriptor. The following format is used for adding permissions (where PERMISSION_NAME is the name of an Android permission):

<android> 
                            <manifestAdditions> 
                            <![CDATA[ 
                            <manifest> 
                            <uses-permission android:name="android.permission.PERMISSION_NAME" /> 
                            </manifest> 
                            ]]> 
                            </manifestAdditions> 
                            </android>

The uses-permissions statements inside the manifest element are added directly to the Android manifest document.

The following permissions are required to use various AIR features:

ACCESS_COARSE_LOCATION

Allows the application to access WIFI and cellular network location data through the Geolocation class.

ACCESS_FINE_LOCATION

Allows the application to access GPS data through the Geolocation class.

ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE

Allows the application to access network information the NetworkInfo class.

CAMERA

Allows the application to access the camera.

Note: When you ask for permission to use the camera feature, Android assumes that your application also requires the camera. If the camera is an optional feature of your application, then you should add a uses-feature element to the manifest for the camera, setting the required attribute to false. See Android compatibility filtering.

INTERNET

Allows the application to make network requests. Also allows remote debugging.

READ_PHONE_STATE

Allows the AIR runtime to mute audio during phone calls. You should set this permission if your app plays audio while in the background.

RECORD_AUDIO

Allows the application to access the microphone.

WAKE_LOCK and DISABLE_KEYGUARD

Allows the application to prevent the device from going to sleep using the SystemIdleMode class settings.

WRITE_EXTERNAL_STORAGE

Allows the application to write to the external memory card on the device.

For example, to set the permissions for an app that impressively requires every permission, you could add the following to the application descriptor:

<android> 
                            <manifestAdditions> 
                            <![CDATA[ 
                            <manifest> 
                            <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> 
                            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> 
                            <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
                            <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 
                            <uses-permission android:name="android.permission.CAMERA" /> 
                            <uses-permission android:name="android.permission.DISABLE_KEYGUARD" /> 
                            <uses-permission android:name="android.permission.INTERNET" /> 
                            <uses-permission android:name="android.permission.READ_PHONE_STATE" /> 
                            <uses-permission android:name="android.permission.RECORD_AUDIO" /> 
                            <uses-permission android:name="android.permission.WAKE_LOCK" /> 
                            <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 
                            </manifest> 
                            ]]> 
                            </manifestAdditions> 
                            </android>

You can use a custom URI scheme to launch an AIR application from a web page or a native Android application. Custom URI support relies on intent filters specified in the Android manifest, so this technique cannot be used on other platforms.

To use a custom URI, add an intent-filter to the application descriptor within the <android> block. Both intent-filter elements in the following example must be specified. Edit the <data android:scheme="my-customuri"/> statement to reflect the URI string for your custom scheme.

<android> 
                            <manifestAdditions> 
                            <![CDATA[ 
                            <manifest> 
                            <application> 
                            <activity> 
                            <intent-filter> 
                            <action android:name="android.intent.action.MAIN"/> 
                            <category android:name="android.intent.category.LAUNCHER"/> 
                            </intent-filter> 
                            <intent-filter> 
                            <action android:name="android.intent.action.VIEW"/> 
                            <category android:name="android.intent.category.BROWSABLE"/> 
                            <category android:name="android.intent.category.DEFAULT"/> 
                            <data android:scheme="my-customuri"/> 
                            </intent-filter> 
                            </activity> 
                            </application> 
                            </manifest> 
                            ]]> 
                            </manifestAdditions> 
                            </android>

An intent filter informs the Android operating system that your application is available to perform a given action. In the case of a custom URI, this means that the user has clicked a link using that URI scheme (and the browser does not know how to handle it).

When your application is invoked through a custom URI, the NativeApplication object dispatches an invoke event. The URL of the link, including query parameters, is placed in the arguments array of the InvokeEvent object. You can use any number of intent-filters.

The Android operating system uses a number of elements in the application manifest file to determine whether your application is compatible with a given device. Adding this information to the manifest is optional. If you do not include these elements, your application can be installed on any Android device. However, it may not operate properly on any Android device. For example, a camera app will not be very useful on a phone that does not have a camera.

The Android manifest tags that you can use for filtering include:

• supports-screens

• uses-configuration

• uses-feature

• uses-sdk (in AIR 3+)

<android> 
                                <manifestAdditions> 
                                <![CDATA[ 
                                <manifest> 
                                <uses-permission android:name="android.permission.CAMERA" /> 
                                <uses-feature android:name="android.hardware.camera" android:required="false"/> 
                                <uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/> 
                                <uses-feature android:name="android.hardware.camera.flash" android:required="false"/> 
                                </manifest> 
                                ]]> 
                                </manifestAdditions> 
                                </android>

<android> 
                                <manifestAdditions> 
                                <![CDATA[ 
                                <manifest> 
                                <uses-permission android:name="android.permission.RECORD_AUDIO" /> 
                                <uses-feature android:name="android.hardware.microphone" android:required="false"/> 
                                </manifest> 
                                ]]> 
                                </manifestAdditions> 
                                </android>

You can permit your application to be installed or moved to the external memory card by setting the installLocation attribute of the Android manifest element to either auto or preferExternal:

<android> 
                            <manifestAdditions> 
                            <![CDATA[ 
                            <manifest android:installLocation="preferExternal"/> 
                            ]]> 
                            </manifestAdditions> 
                            </android>

The Android operating system doesn’t guarantee that your app will be installed to the external memory. A user can also move the app between internal and external memory using the system settings app.

Even when installed to external memory, application cache and user data, such as the contents of the app-storage directory, shared objects, and temporary files, are still stored in the internal memory. To avoid using too much internal memory, be selective about the data you save to the application storage directory. Large amounts of data should be saved to the SDCard using the File.userDirectory or File.documentsDirectory locations (which both map to the root of the SD card on Android).

In Android 3.0+, an application must enable hardware acceleration in the Android application element in order for plug-in content to be displayed in a StageWebView object. To enable plug-in rendering, set the android:hardwareAccelerated attribute of the application element to true:

<android> 
                            <manifestAdditions> 
                            <![CDATA[ 
                            <manifest> 
                            <application android:hardwareAccelerated="true"/> 
                            </manifest> 
                            ]]> 
                            </manifestAdditions> 
                            </android>

In AIR 3 and later, the runtime sets the display to render 32-bit colors. In earlier versions of AIR, the runtime uses 16-bit color. You can instruct the runtime to use 16-bit color using the <colorDepth> element of the application descriptor:

<android> 
                            <colorDepth>16bit</colorDepth> 
                            <manifestAdditions>...</manifestAdditions> 
                            </android>

Using the 16-bit color depth can increase rendering performance, but at the expense of color fidelity.

Adobe AIR 3.3 and higher supports multitasking on iOS by enabling certain background behaviors:

• Audio

• Location updates

• Networking

• Opting out of background app execution

<InfoAdditions> 
                                <![CDATA[ 
                                <key>UIBackgroundModes</key> 
                                <array> 
                                <string>audio</string> 
                                </array> 
                                ]]> 
                                </InfoAdditions>

<InfoAdditions> 
                                <![CDATA[ 
                                <key>UIBackgroundModes</key> 
                                <array> 
                                <string>location</string> 
                                </array> 
                                ]]> 
                                </InfoAdditions>

<InfoAdditions> 
                                <![CDATA[ 
                                <key>UIApplicationExitsOnSuspend</key> 
                                <true/> 
                                ]]> 
                                </InfoAdditions>

AIR sets several entries in the generated Info.plist file to ensure that application and runtime features work correctly. You cannot define the following settings:

For iPad support, include the proper key-value settings for UIDeviceFamily within your InfoAdditions element. The UIDeviceFamily setting is an array of strings. Each string defines supported devices. The <string>1</string> setting defines support for the iPhone and iPod Touch. The <string>2</string> setting defines support for the iPad.The <string>3</string> setting defines support for the tvOS. If you specify only one of these strings, only that device family is supported. For example, the following setting limits support to the iPad:

<key>UIDeviceFamily</key> 
                            <array> 
                            <string>2</string> 
                            </array>>

The following setting supports both device families (iPhone/iPod Touch and iPad):

<key>UIDeviceFamily</key> 
                            <array> 
                            <string>1</string> 
                            <string>2</string> 
                            </array>

The following setting limits support for tvOS:

<key>UIDeviceFamily</key> 
                            <array> 
                            <string>3</string> 
                            </array>

• Warning: Provisioning profile specified for tvOS, ignoring iOS UIDeviceFamily value(s).

• Warning: Provisioning profile specified for iOS, ignoring tvOS UIDeviceFamily value(s).

Additionally, in AIR 3.7 and higher, you can use the forceCPURenderModeForDevices tag to force CPU render mode for a specified set of devices and enable GPU render mode for remaining iOS devices.

You add this tag as a child of the iPhone tag and specify a space-separated list of device model names. For a list of valid device model names, see forceCPURenderModeForDevices.

For example, to use CPU mode in old iPods, iPhones, and iPads and enable GPU mode for all other devices, specify the following in the application descriptor:

... 
                            <renderMode>GPU</renderMode> 
                            ... 
                            <iPhone> 
                            ... 
                               <forceCPURenderModeForDevices>iPad1,1 iPhone1,1 iPhone1,2 iPod1,1 
                               </forceCPURenderModeForDevices> 
                            </iPhone>

The requestedDisplayResolution element specifies whether your application should use the standard or high resolution mode on iOS devices with high-resolution screens.

<requestedDisplayResolution>high</requestedDisplayResolution>

In high-resolution mode, you can address each pixel on a high-resolution display individually. In the standard mode, the device screen will appear to your application as a standard resolution screen. Drawing a single pixel in this mode will set the color of four pixels on the high-resolution screen.

The default setting is standard. Note that for targeting iOS devices, you use the requestedDisplayResolution element as a child of the iPhone element (not the InfoAdditions element or initialWindow element).

If you want to use different settings on different devices, specify your default value as the requestedDisplayResolution element’s value. Use the excludeDevices attribute to specify devices that should use the opposite value. For example, with the following code, high resolution mode is used for all devices that support it except 3rd-generation iPads, which use standard mode:

<requestedDisplayResolution excludeDevices="iPad3">high</requestedDisplayResolution>

The excludeDevices attribute is available in AIR 3.6 and later.

You can register a custom URI scheme to allow your application to be invoked by a link in a web page or another, native application on the device. To register a URI scheme, add a CFBundleURLTypes key to the InfoAdditions element. The following example registers a URI scheme named com.example.app to allow an application to be invoked by URLs with the form: example://foo.

<key>CFBundleURLTypes</key> 
                            <array> 
                            <dict> 
                            <key>CFBundleURLSchemes</key> 
                            <array> 
                            <string>example</string> 
                            </array> 
                            <key>CFBundleURLName</key> 
                            <string>com.example.app</string> 
                            </dict> 
                            </array>

When your application is invoked through a custom URI, the NativeApplication object dispatches an invoke event. The URL of the link, including query parameters, is placed in the arguments array of the InvokeEvent object. You can use any number of custom URI schemes.

Add entries to a UIRequiredDeviceCapabilities array within the InfoAdditions element if your application should only be used on devices with specific hardware or software capabilities. For example, the following entry indicates that an application requires a still camera and a microphone:

<key>UIRequiredDeviceCapabilities</key> 
                            <array> 
                            <string>microphone</string> 
                            <string>still-camera</string> 
                            </array>

If a device lacks the corresponding capability, the application cannot be installed. The capability settings relevant to AIR applications include:

AIR 2.6+ automatically adds armv7 and opengles-2 to the list of required capabilities.

When a user switches away from an AIR application it enters the background and pauses. If you want your application to exit completely instead of pausing, set the UIApplicationExitsOnSuspend property to YES:

<key>UIApplicationExitsOnSuspend</key> 
                            <true/>

You can minimize your initial application download size by packaging a subset of the SWFs used by your application and loading the remaining (asset-only) external SWFs at runtime using the Loader.load() method. To use this feature, you must package the application such that ADT moves all ActionScript ByteCode (ABC) from the externally loaded SWF files to the main application SWF, leaving a SWF file that contains only assets. This is to conform with the Apple Store’s rule that forbids downloading any code after an application is installed.

ADT does the following to support externally loaded SWFs (also called stripped SWFs):

• Reads the text file specified in the <iPhone> element’s <externalSwfs> subelement to access the line-delimited list of SWFs to be loaded at execution time:

  <iPhone> 
                                         ... 
                                         <externalSwfs>FilewithPathsOfSWFsThatAreToNotToBePackaged.txt</externalSwfs> 
                                      </iPhone>

• Transfers the ABC code from each externally loaded SWF to the main executable.

• Omits the externally loaded SWFs from the .ipa file.

• Copies the stripped SWFs to the .remoteStrippedSWFs directory. You host these SWFs on a web server and your application loads them, as necessary, at runtime.

You indicate the SWF files to be loaded at runtime by specifying their names, one per line in a text file, as the following example shows:

assets/Level1/Level1.swf 
                            assets/Level2/Level2.swf 
                            assets/Level3/Level3.swf 
                            assets/Level4/Level4.swf

The file path specified is relative to the application descriptor file. Additionally, you must specify these swfs as assets in the adt command.

 For more information on this feature, including sample code, see External hosting of secondary SWFs for AIR apps on iOS, a blog post by Adobe engineer Abhinav Dhandh.

For Geolocation support, add one of the following key-value pairs to the InfoAdditions element:

<InfoAdditions> 
                            <![CDATA[ 
                            <key>NSLocationAlwaysUsageDescription</key> 
                            <string>Sample description to allow geolocation always</string> 
                            <key>NSLocationWhenInUseUsageDescription</key> 
                            <string>Sample description to allow geolocation when application is in foreground</string> 
                            <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
                            <string>Sample description to allow geolocation always and when application is in foreground</string>
                            ]]> 
                            </InfoAdditions>

In addition to the application icons, you must also provide at least one launch image named Default.png. Optionally, you can include separate launch images for different starting orientations, different resolutions (including high-resolution retina display and 16:9 aspect ratio), and different devices. You can also include different launch images to be used when your application is invoked through a URL.

Launch image files are not referenced in the application descriptor and must be placed in the root application directory. (Do not put the files in a subdirectory.)

basename + screen size modifier + urischeme + orientation + scale + device + .png