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

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>

AIR validates the elements and attributes included in the Android portion of the application descriptor. By default, AIR validates against the Android 2.2 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.

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.