Android settings

On the Android platform, you can use the android element of the application descriptor to add information to the Android application manifest, which is an application properties file used by the Android operating system. ADT automatically generates the Android Manifest.xml file when you create the APK package. AIR sets a few properties to the values required for certain features to work. Any other properties set in the android section of the AIR application descriptor are added to the corresponding section of the Manifest.xml file.

Note: For most AIR applications, you must set the Android permissions needed by your application within the android element, but you generally will not need to set any other properties.

You can only set attributes that take string, integer, or boolean values. Setting references to resources in the application package is not supported.

Note: The runtime requires a minimum SDK version greater than 9. You should ensure that the Manifest includes <uses-sdk android:minSdkVersion="9"></uses-sdk>.

Reserved Android manifest settings

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:

manifest element

You cannot set the following attributes of the manifest element:

  • package

  • android:versionCode

  • android:versionName

  • xmlns:android

activity element

You cannot set the following attributes for the main activity element:

  • android:label

  • android:icon

application element

You cannot set the following attributes of the application element:

  • android:theme

  • android:name

  • android:label

  • android:windowSoftInputMode

  • android:configChanges

  • android:screenOrientation

  • android:launchMode

Android permissions

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>

Android custom URI schemes

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.

Note: Links in a StageWebView instance cannot open URLs that use a custom URI scheme.

Android compatibility filtering

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

Camera applications

If you request the camera permission for your application, Android assumes that the app requires all available camera features, including auto-focus and flash. If your app does not require all camera features, or if the camera is an optional feature, you should set the various uses-feature elements for the camera to indicate that these are optional. Otherwise, users with devices that are missing one feature or that do not have a camera at all, will not be able to find your app on the Android Market.

The following example illustrates how to request permission for the camera and make all camera features optional:

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

Audio recording applications

If you request the permission to record audio, Android also assumes that the app requires a microphone. If audio recording is an optional feature of your app, you can add a uses-feature tag to specify that the microphone is not required. Otherwise, users with devices that do not have a microphone, will not be able to find your app on the Android Market.

The following example illustrates how to request permission to use the microphone while still making the microphone hardware optional:

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

Android 3 menu button

In Android 3, which runs on tablet devices, applications are expected to provide their own button for opening an options menu. The Android SDK now provides an ActionBar component that displays a menu button. The menu button displayed by the OS at the bottom of the tablet screen (next to the Back, Home, and Recent Apps buttons) is no longer shown for applications that target Android SDK level 11+.

Install location

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

Enabling Flash Player and other plug-ins in a StageWebView object

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>

AIR validates the elements and attributes included in the Android portion of the application descriptor. By default, AIR validates against the Android 2.3 SDK. Since the android:hardwareAccelerated attribute was added in Android 3.0, you must set the AIR ADT utility to validate against the Android 3.0 SDK (or later).

First, download the Android 3 SDK: Android Developers: Installing the SDK . When packaging, set the -platformsdk option to the path containing the appropriate Android SDK (set the path to the directory containing the Android tools folder). For example:

adt -package 
    -target apk 
    -storetype pkcs12 -keystore cert.p12 -storepass foo 
    myApp.apk 
    myApp-app.xml 
    -platformsdk c:\androidSDK 
    myApp.swf 
    other.files

You can also set the AIR_ANDROID_SDK_HOME environment variable to the path containing the Android SDK. Since Flash Builder and Flash Professional do not allow you to add extra parameters when packaging, setting this environment variable allows you to use Android SDK settings that were not available when the AIR SDK you are using was released. See ADT environment variables.

Color depth

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.