<uses-feature android:name="string" android:required=["true" | "false"] android:glEsVersion="integer" />
<manifest>
Android Market and <uses-feature> elements
Android Market filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their devices. One of the ways Market filters applications is by feature compatibility.
To do this, Market checks the
<uses-feature> elements in each application's manifest, to
establish the app's feature needs. Market then shows or hides the application to
each user, based on a comparison with the features available on the user's
device.
By specifying the features that your application requires, you enable Android Market to present your application only to users whose devices meet the application's feature requirements, rather than presenting it to all users.
For important information about how Android Market uses features as the basis for filtering, please read Android Market and Feature-Based Filtering, below.
The purpose of a <uses-feature> declaration is to inform
any external entity of the set of hardware and software features on which your
application depends. The element offers a required attribute that
lets you specify whether your application requires and cannot function without
the declared feature, or whether it prefers to have the feature but can function
without it. Because feature support can vary across Android devices, the
<uses-feature> element serves an important role in letting an
application describe the device-variable features that it uses.
The set of available features that your application declares corresponds to
the set of feature constants made available by the Android PackageManager, which are listed for
convenience in the Features Reference tables
at the bottom of this document.
You must specify each feature in a separate <uses-feature>
element, so if your application requires multiple features, it would declare
multiple <uses-feature> elements. For example, an application
that requires both Bluetooth and camera features in the device would declare
these two elements:
<uses-feature android:name="android.hardware.bluetooth" /> <uses-feature android:name="android.hardware.camera" />
In general, you should always make sure to declare
<uses-feature> elements for all of the features that your
application requires.
Declared <uses-feature> elements are informational only, meaning
that the Android system itself does not check for matching feature support on
the device before installing an application. However, other services
(such as Android Market) or applications may check your application's
<uses-feature> declarations as part of handling or interacting
with your application. For this reason, it's very important that you declare all of
the features (from the list below) that your application uses.
For some features, there may exist a specfic attribute that allows you to define
a version of the feature, such as the version of Open GL used (declared with
glEsVersion). Other features that either do or do not
exist for a device, such as a camera, are declared using the
name attribute.
Although the <uses-feature> element is only activated for
devices running API Level 4 or higher, it is recommended to include these
elements for all applications, even if the minSdkVersion
is "3" or lower. Devices running older versions of the platform will simply
ignore the element.
Note: When declaring a feature, remember
that you must also request permissions as appropriate. For example, you must
still request the CAMERA
permission before your application can access the camera API. Requesting the
permission grants your application access to the appropriate hardware and
software, while declaring the features used by your application ensures proper
device compatibility.
android:nameandroid:requiredandroid:name.
"android:required="true" for a feature,
you are specifying that the application cannot function, or is not
designed to function, when the specified feature is not present on the
device. "android:required="false" for a feature, it
means that the application prefers to use the feature if present on
the device, but that it is designed to function without the specified
feature, if necessary. The default value for android:required if not declared is
"true".
android:glEsVersionAn application should specify at most one android:glEsVersion
attribute in its manifest. If it specifies more than one, the
android:glEsVersion with the numerically highest value is used and
any other values are ignored.
If an application does not specify an android:glEsVersion
attribute, then it is assumed that the application requires only OpenGL ES 1.0,
which is supported by all Android-powered devices.
An application can assume that if a platform supports a given OpenGL ES version, it also supports all numerically lower OpenGL ES versions. Therefore, an application that requires both OpenGL ES 1.0 and OpenGL ES 2.0 must specify that it requires OpenGL ES 2.0.
An application that can work with any of several OpenGL ES versions should only specify the numerically lowest version of OpenGL ES that it requires. (It can check at run-time whether a higher level of OpenGL ES is available.)
Android Market filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their devices. One of the ways Market filters applications is by feature compatibility.
To determine an application's feature compatibility with a given user's device, the Android Market service compares:
<uses-feature> elements in its manifest To ensure an accurate comparison of features, the Android Package Manager
provides a shared set of feature constants that both applications and devices
use to declare feature requirements and support. The available feature constants
are listed in the Features Reference tables at
the bottom of this document, and in the class documentation for PackageManager.
When the user launches the Market application, the application queries the
Package Manager for the list of features available on the device by calling
getSystemAvailableFeatures(). The
Market application then passes the features list up to the Android Market
service when establishing the session for the user.
Each time you upload an application to the Android Market Publisher Site,
Android Market scans the application's manifest file. It looks for
<uses-feature> elements and evaluates them in combination
with other elements, in some cases, such as <uses-sdk> and
<uses-permission> elements. After establishing the
application's set of required features, it stores that list internally as
metadata associated with the application .apk and the application
version.
When a user searches or browses for applications using the Android Market application, the service compares the features needed by each application with the features available on the user's device. If all of an application's required features are present on the device, Android Market allows the user to see the application and potentially download it. If any required feature is not supported by the device, Android Market filters the application so that it is not visible to the user and not available for download.
Because the features you declare in <uses-feature>
elements directly affect how Android Market filters your application, it's
important to understand how Android Market evaluates the application's manifest
and establishes the set of required features. The sections below provide more
information.
An explicitly declared feature is one that your application declares in a
<uses-feature> element. The feature declaration can include
an android:required=["true" | "false"] attribute (if you are
compiling against API level 5 or higher), which lets you specify whether the
application absolutely requires the feature and cannot function properly without
it ("true"), or whether the application prefers to use the feature
if available, but is designed to run without it ("false").
Android Market handles explictly declared features in this way:
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera" android:required="false" />
android:required attribute, Android Market assumes that the feature
is required and sets up filtering on it. In general, if your application is designed to run on Android 1.6 and earlier
versions, the android:required attribute is not available in the
API and Android Market assumes that any and all
<uses-feature> declarations are required.
Note: By declaring a feature explicitly and
including an android:required="false" attribute, you can
effectively disable all filtering on Android Market for the specified feature.
An implicit feature is one that an application requires in order to
function properly, but which is not declared in a
<uses-feature> element in the manifest file. Strictly
speaking, every application should always declare all features that it
uses or requires, so the absence of a declaration for a feature used by an
application should be considered an error. However, as a safeguard for users and
developers, Android Market looks for implicit features in each application and
sets up filters for those features, just as it would do for an explicitly
declared feature.
An application might require a feature but not declare it because:
<uses-feature> element was
not available.<uses-feature>
element name or an unrecognized string value for the
android:name attribute would invalidate the feature declaration.
To account for the cases above, Android Market attempts to discover an
application's implied feature requirements by examining other elements
declared in the manifest file, specifically,
<uses-permission> elements.
If an application requests hardware-related permissions, Android Market
assumes that the application uses the underlying hardware features and
therefore requires those features, even though there might be no
corresponding to <uses-feature> declarations. For such
permissions, Android Market adds the underlying hardware features to the
metadata that it stores for the application and sets up filters for them.
For example, if an application requests the CAMERA permission
but does not declare a <uses-feature> element for
android.hardware.camera, Android Market considers that the
application requires a camera and should not be shown to users whose devices do
not offer a camera.
If you don't want Android Market to filter based on a specific implied
feature, you can disable that behavior. To do so, declare the feature explicitly
in a <uses-feature> element and include an
android:required="false" attribute. For example, to disable
filtering derived from the CAMERA permission, you would declare
the feature as shown below.
<uses-feature android:name="android.hardware.camera" android:required="false" />
It's important to understand that the permissions that you
request in <uses-permission> elements can directly affect how
Android Market filters your application. The reference section Permissions that Imply Feature Requirements,
below, lists the full set of permissions that imply feature requirements and
therefore trigger filtering.
Android Market applies slightly different rules than described above, when determining filtering for Bluetooth.
If an application declares a Bluetooth permission in a
<uses-permission> element, but does not explicitly declare
the Bluetooth feature in a <uses-feature> element, Android
Market checks the version(s) of the Android platform on which the application is
designed to run, as specified in the <uses-sdk> element.
As shown in the table below, Android Market enables filtering for the
Bluetooth feature only if the application declares its lowest or targeted
platform as Android 2.0 (API level 5) or higher. However, note that Android
market applies the normal rules for filtering when the application explicitly
declares the Bluetooth feature in a <uses-feature> element.
Table 1. How Android Market determines the
Bluetooth feature requirement for an application that requests a Bluetooth
permission but does not declare the Bluetooth feature in a
<uses-feature> element.
minSdkVersion is ... |
targetSdkVersion is |
Result |
|---|---|---|
| <=4 | Android Market will not filter the application from any devices
based on their reported support for the android.hardware.bluetooth
feature. |
|
| <=4 | >=5 | Android Market filters the application from any devices that
do not support the android.hardware.bluetooth feature (including
older releases). |
| >=5 | >=5 |
The examples below illustrate the different filtering effects, based on how Android Market handles the Bluetooth feature.
<uses-feature> element.<manifest ...>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-sdk android:minSdkVersion="3" />
...
</manifest>
<manifest ...>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
</manifest>
<manifest ...>
<uses-feature android:name="android.hardware.bluetooth" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
</manifest>
android:required="false" attribute.<manifest ...>
<uses-feature android:name="android.hardware.bluetooth" android:required="false" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
</manifest>
You can use the aapt tool, included in the Android SDK, to
determine how Android Market will filter your application, based on its declared
features and permissions. To do so, run aapt with the dump
badging command. This causes aapt to parse your
application's manifest and apply the same rules as used by Android Market to
determine the features that your application requires.
To use the tool, follow these steps:
.apk.
If you are developing in Eclipse with ADT, right-click the project and select
Android Tools > Export Unsigned Application
Package. Select a destination filename and path and click
OK. aapt tool, if it is not already in your PATH.
If you are using SDK Tools r8 or higher, you can find aapt in the
<SDK>/platform-tools/ directory.
Note: You must use the version of
aapt that is provided for the latest Platform-Tools component available. If
you do not have the latest Platform-Tools component, download it using the Android SDK and AVD Manager.
aapt using this syntax: $ aapt dump badging <path_to_exported_.apk>
Here's an example of the command output for the second Bluetooth example, above:
$ ./aapt dump badging BTExample.apk package: name='com.example.android.btexample' versionCode='' versionName='' uses-permission:'android.permission.BLUETOOTH_ADMIN' uses-feature:'android.hardware.bluetooth' sdkVersion:'3' targetSdkVersion:'5' application: label='BT Example' icon='res/drawable/app_bt_ex.png' launchable activity name='com.example.android.btexample.MyActivity'label='' icon='' uses-feature:'android.hardware.touchscreen' main supports-screens: 'small' 'normal' 'large' locales: '--_--' densities: '160'
The tables below provide reference information about hardware and software features and the permissions that can imply them on Android Market.
The table below describes the hardware feature descriptors supported by the
most current platform release. To signal that your application uses or requires
a hardware feature, declare each value in a android:name attribute
in a separate <uses-feature> element.
| Feature Type | Feature Descriptor | Description | Comments |
|---|---|---|---|
| Audio | android.hardware.audio.low_latency |
The application uses a low-latency audio pipeline on the device and is sensitive to delays or lag in sound input or output. | |
| Bluetooth | android.hardware.bluetooth |
The application uses Bluetooth radio features in the device. | |
| Camera | android.hardware.camera |
The application uses the device's camera. If the device supports multiple cameras, the application uses the camera that facing away from the screen. | |
android.hardware.camera.autofocus |
Subfeature. The application uses the device camera's autofocus capability. | If declared with the "android:required="true"
attribute, these subfeatures implicitly declare the
android.hardware.camera parent feature. |
|
android.hardware.camera.flash |
Subfeature. The application uses the device camera's flash. | ||
android.hardware.camera.front |
Subfeature. The application uses a front-facing camera on the device. | ||
| Location | android.hardware.location |
The application uses one or more features on the device for determining location, such as GPS location, network location, or cell location. | |
android.hardware.location.network |
Subfeature. The application uses coarse location coordinates obtained from a network-based geolocation system supported on the device. | If declared with the "android:required="true"
attribute, these subfeatures implicitly declare the
android.hardware.location parent feature. |
|
android.hardware.location.gps |
Subfeature. The application uses precise location coordinates obtained from a Global Positioning System receiver on the device. | ||
| Microphone | android.hardware.microphone |
The application uses a microphone on the device. | |
| Near Field Communications | android.hardware.nfc |
The application uses NFC radio features in the device. | |
| Sensors | android.hardware.sensor.accelerometer |
The application uses motion readings from an accelerometer on the device. | |
android.hardware.sensor.barometer |
The application uses the device's barometer. | ||
android.hardware.sensor.compass |
The application uses directional readings from a magnetometer (compass) on the device. | ||
android.hardware.sensor.gyroscope |
The application uses the device's gyroscope sensor. | ||
android.hardware.sensor.light |
The application uses the device's light sensor. | ||
android.hardware.sensor.proximity |
The application uses the device's proximity sensor. | ||
| Telephony | android.hardware.telephony |
The application uses telephony features on the device, such as telephony radio with data communication services. | |
android.hardware.telephony.cdma |
Subfeature. The application uses CDMA telephony radio features on the device. | If declared with the "android:required="true"
attribute, these subfeatures implicitly declare the
android.hardware.telephony parent feature. |
|
android.hardware.telephony.gsm |
Subfeature. The application uses GSM telephony radio features on the device. | ||
| Touchscreen | android.hardware.faketouch |
The application uses basic touch interaction events, such as "click down", "click up", and drag. | When declared, this indicates that the application is compatible with a device that offers an emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input system that can emulate a subset of touchscreen capabilities. An example of such an input system is a mouse or remote control that drives an on-screen cursor. If your application does not require complicated gestures and you want your application available to devices with an emulated touchscreen, you should declare this feature. |
android.hardware.touchscreen |
The application uses touchscreen capabilities, for gestures more interactive than basic touches, such as a fling. This is a superset of the faketouch features. | ||
android.hardware.touchscreen.multitouch |
The application uses basic two-point multitouch capabilities on the device screen, such as for pinch gestures, but does not need to track touches independently. This is a superset of touchscreen features. | If declared with the "android:required="true" attribute, this
implicitly declares the android.hardware.touchscreen
parent feature. |
|
android.hardware.touchscreen.multitouch.distinct |
Subfeature. The application uses advanced multipoint multitouch capabilities on the device screen, such as for tracking two or more points fully independently. This is a superset of multitouch features. | If declared with the "android:required="true" attribute, this
implicitly declares the
android.hardware.touchscreen.multitouch parent feature. |
|
android.hardware.touchscreen.multitouch.jazzhand |
The application uses advanced multipoint multitouch capabilities on the device screen, for tracking up to five points fully independently. This is a superset of distinct multitouch features. | ||
| Wifi | android.hardware.wifi |
The application uses 802.11 networking (wifi) features on the device. |
The table below describes the software feature descriptors supported by the
most current platform release. To signal that your application uses or requires
a software feature, declare each value in a android:name attribute
in a separate <uses-feature> element.
| Feature | Attribute Value | Description | Comments |
|---|---|---|---|
| Live Wallpaper | android.software.live_wallpaper |
The application uses or provides Live Wallpapers. | |
| SIP/VOIP | android.software.sip |
The application uses SIP service on the device. | |
android.software.sip.voip |
Subfeature. The application uses SIP-based VOIP service on the device. | If declared with the "android:required="true" attribute, this
subfeature implicitly declares the android.software.sip
parent feature. |
Some feature constants listed in the tables above were made available to
applications after the corresponding API; for example, the
android.hardware.bluetooth feature was added in Android 2.2 (API
level 8), but the bluetooth API that it refers to was added in Android 2.0 (API
level 5). Because of this, some apps were able to use the API before they had
the ability to declare that they require the API via the
<uses-feature> system.
To prevent those apps from being made available unintentionally, Android
Market assumes that certain hardware-related permissions indicate that the
underlying hardware features are required by default. For instance, applications
that use Bluetooth must request the BLUETOOTH permission in a
<uses-permission> element — for legacy apps, Android
Market assumes that the permission declaration means that the underlying
android.hardware.bluetooth feature is required by the application
and sets up filtering based on that feature.
The table below lists permissions that imply feature requirements
equivalent to those declared in <uses-feature> elements. Note
that <uses-feature> declarations, including any declared
android:required attribute, always take precedence over features
implied by the permissions below.
For any of the permissions below, you can disable filtering based on the
implied feature by explicitly declaring the implied feature explicitly, in a
<uses-feature> element, with an
android:required="false" attribute. For example, to disable any
filtering based on the CAMERA permission, you would add this
<uses-feature> declaration to the manifest file:
<uses-feature android:name="android.hardware.camera" android:required="false" />
| Category | This Permission... | Implies This Feature Requirement |
|---|---|---|
| Bluetooth | BLUETOOTH |
android.hardware.bluetooth
(See Special handling for Bluetooth feature for details.) |
BLUETOOTH_ADMIN |
android.hardware.bluetooth |
|
| Camera | CAMERA |
android.hardware.camera and
android.hardware.camera.autofocus |
| Location | ACCESS_MOCK_LOCATION |
android.hardware.location |
ACCESS_LOCATION_EXTRA_COMMANDS |
android.hardware.location |
|
INSTALL_LOCATION_PROVIDER |
android.hardware.location |
|
ACCESS_COARSE_LOCATION |
android.hardware.location.network and
android.hardware.location |
|
ACCESS_FINE_LOCATION |
android.hardware.location.gps and
android.hardware.location |
|
| Microphone | RECORD_AUDIO |
android.hardware.microphone |
| Telephony | CALL_PHONE |
android.hardware.telephony |
CALL_PRIVILEGED |
android.hardware.telephony |
|
MODIFY_PHONE_STATE |
android.hardware.telephony |
|
PROCESS_OUTGOING_CALLS |
android.hardware.telephony |
|
READ_SMS |
android.hardware.telephony |
|
RECEIVE_SMS |
android.hardware.telephony |
|
RECEIVE_MMS |
android.hardware.telephony |
|
RECEIVE_WAP_PUSH |
android.hardware.telephony |
|
SEND_SMS |
android.hardware.telephony |
|
WRITE_APN_SETTINGS |
android.hardware.telephony |
|
WRITE_SMS |
android.hardware.telephony |
|
| Wifi | ACCESS_WIFI_STATE |
android.hardware.wifi |
CHANGE_WIFI_STATE |
android.hardware.wifi |
|
CHANGE_WIFI_MULTICAST_STATE |
android.hardware.wifi |