Google Play uses the <uses-sdk> attributes declared in your app manifest to filter your app from devices that do not meet it's platform version requirements. Before setting these attributes, make sure that you understand Google Play filters.
Lets you express an application's compatibility with one or more versions of the Android platform, by means of an API Level integer. The API Level expressed by an application will be compared to the API Level of a given Android system, which may vary among different Android devices.
Despite its name, this element is used to specify the API Level, not the version number of the SDK (software development kit) or Android platform. The API Level is always a single integer. You cannot derive the API Level from its associated Android version number (for example, it is not the same as the major version or the sum of the major and minor versions).
Caution: If you do not declare this attribute, the system assumes a default value of "1", which indicates that your application is compatible with all versions of Android. If your application is not compatible with all versions (for instance, it uses APIs introduced in API Level 3) and you have not declared the proper minSdkVersion, then when installed on a system with an API Level less than 3, the application will crash during runtime when attempting to access the unavailable APIs. For this reason, be certain to declare the appropriate API Level in the minSdkVersion attribute.
This attribute informs the system that you have tested against the target version and the system should not enable any compatibility behaviors to maintain your app's forward-compatibility with the target version. The application is still able to run on older versions (down to minSdkVersion).
As Android evolves with each new version, some behaviors and even appearances might change. However, if the API level of the platform is higher than the version declared by your app's targetSdkVersion, the system may enable compatibility behaviors to ensure that your app continues to work the way you expect. You can disable such compatibility behaviors by specifying targetSdkVersion to match the API level of the platform on which it's running. For example, setting this value to "11" or higher allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or higher and also disables screen compatibility mode when running on larger screens (because support for API level 11 implicitly supports larger screens).
There are many compatibility behaviors that the system may enable based on the value you set for this attribute. Several of these behaviors are described by the corresponding platform versions in the Build.VERSION_CODES reference.
To maintain your application along with each Android release, you should increase the value of this attribute to match the latest API level, then thoroughly test your application on the corresponding platform version.
In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this attribute when installing an application and when re-validating the application after a system update. In either case, if the application's maxSdkVersion attribute is lower than the API Level used by the system itself, then the system will not allow the application to be installed. In the case of re-validation after system update, this effectively removes your application from the device.
To illustrate how this attribute can affect your application after system updates, consider the following example:
An application declaring maxSdkVersion="5" in its manifest is published on Google Play. A user whose device is running Android 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user receives an over-the-air system update to Android 2.0 (API Level 5). After the update is installed, the system checks the application's maxSdkVersion and successfully re-validates it. The application functions as normal. However, some time later, the device receives another system update, this time to Android 2.0.1 (API Level 6). After the update, the system can no longer re-validate the application because the system's own API Level (6) is now higher than the maximum supported by the application (5). The system prevents the application from being visible to the user, in effect removing it from the device.
Warning: Declaring this attribute is not recommended. First, there is no need to set the attribute as means of blocking deployment of your application onto new versions of the Android platform as they are released. By design, new versions of the platform are fully backward-compatible. Your application should work properly on new versions, provided it uses only standard APIs and follows development best practices. Second, note that in some cases, declaring the attribute can result in your application being removed from users' devices after a system update to a higher API Level. Most devices on which your application is likely to be installed will receive periodic system updates over the air, so you should consider their effect on your application before setting this attribute.
Future versions of Android (beyond Android 2.0.1) will no longer check or enforce the maxSdkVersion attribute during installation or re-validation. Google Play will continue to use the attribute as a filter, however, when presenting users with applications available for download.
It lets the system negotiate the installation of applications on the user's device, such that version-incompatible applications are not installed.
Each Android platform version stores its API Level identifier internally, in the Android system itself.
Applications can use a manifest element provided by the framework API — <uses-sdk> — to describe the minimum and maximum API Levels under which they are able to run, as well as the preferred API Level that they are designed to support. The element offers three key attributes:
android:minSdkVersion — Specifies the minimum API Level on which the application is able to run. The default value is "1".
android:targetSdkVersion — Specifies the API Level on which the application is designed to run. In some cases, this allows the application to use manifest elements or behaviors defined in the target API Level, rather than being restricted to using only those defined for the minimum API Level.
For example, to specify the minimum system API Level that an application requires in order to run, the application would include in its manifest a <uses-sdk> element with a android:minSdkVersion attribute. The value of android:minSdkVersion would be the integer corresponding to the API Level of the earliest version of the Android platform under which the application can run.
When the user attempts to install an application, or when revalidating an appplication after a system update, the Android system first checks the <uses-sdk> attributes in the application's manifest and compares the values against its own internal API Level. The system allows the installation to begin only if these conditions are met:
The principal reason that an application would declare an API Level in android:minSdkVersion is to tell the Android system that it is using APIs that were introduced in the API Level specified. If the application were to be somehow installed on a platform with a lower API Level, then it would crash at run-time when it tried to access APIs that don't exist. The system prevents such an outcome by not allowing the application to be installed if the lowest API Level it requires is higher than that of the platform version on the target device.
For example, the android.appwidget package was introduced with API Level 3. If an application uses that API, it must declare a android:minSdkVersion attribute with a value of "3". The application will then be installable on platforms such as Android 1.5 (API Level 3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and Android 1.0 platforms (API Level 1).
The sections below provide information related to API level that you should consider when developing your application.
Because almost all changes to the framework API are additive, an Android application developed using any given version of the API (as specified by its API Level) is forward-compatible with later versions of the Android platform and higher API levels. The application should be able to run on all later versions of the Android platform, except in isolated cases where the application uses a part of the API that is later removed for some reason.
Forward compatibility is important because many Android-powered devices receive over-the-air (OTA) system updates. The user may install your application and use it successfully, then later receive an OTA update to a new version of the Android platform. Once the update is installed, your application will run in a new run-time version of the environment, but one that has the API and system capabilities that your application depends on.
In some cases, changes below the API, such those in the underlying system itself, may affect your application when it is run in the new environment. For that reason it's important for you, as the application developer, to understand how the application will look and behave in each system environment. To help you test your application on various versions of the Android platform, the Android SDK includes multiple platforms that you can download. Each platform includes a compatible system image that you can run in an AVD, to test your application.
Android applications are not necessarily backward compatible with versions of the Android platform older than the version against which they were compiled.
Each new version of the Android platform can include new framework APIs, such as those that give applications access to new platform capabilities or replace existing API parts. The new APIs are accessible to applications when running on the new platform and, as mentioned above, also when running on later versions of the platform, as specified by API Level. Conversely, because earlier versions of the platform do not include the new APIs, applications that use the new APIs are unable to run on those platforms.
Although it's unlikely that an Android-powered device would be downgraded to a previous version of the platform, it's important to realize that there are likely to be many devices in the field that run earlier versions of the platform. Even among devices that receive OTA updates, some might lag and might not receive an update for a significant amount of time.
When you are developing your application, you will need to choose the platform version against which you will compile the application. In general, you should compile your application against the lowest possible version of the platform that your application can support.
You can determine the lowest possible platform version by compiling the application against successively lower build targets. After you determine the lowest version, you should create an AVD using the corresponding platform version (and API Level) and fully test your application. Make sure to declare a android:minSdkVersion attribute in the application's manifest and set its value to the API Level of the platform version.
If you build an application that uses APIs or system features introduced in the latest platform version, you should set the android:minSdkVersion attribute to the API Level of the latest platform version. This ensures that users will only be able to install your application if their devices are running a compatible version of the Android platform. In turn, this ensures that your application can function properly on their devices.
If your application uses APIs introduced in the latest platform version but does not declare a android:minSdkVersion attribute, then it will run properly on devices running the latest version of the platform, but not on devices running earlier versions of the platform. In the latter case, the application will crash at runtime when it tries to use APIs that don't exist on the earlier versions.
After compiling your application, you should make sure to test it on the platform specified in the application's android:minSdkVersion attribute. To do so, create an AVD that uses the platform version required by your application. Additionally, to ensure forward-compatibility, you should run and test the application on all platforms that use a higher API Level than that used by your application.
The Android SDK includes multiple platform versions that you can use, including the latest version, and provides an updater tool that you can use to download other platform versions as necessary.
To access the updater, use the android command-line tool, located in the <sdk>/tools directory. You can launch the SDK updater by executing android sdk. You can also simply double-click the android.bat (Windows) or android (OS X/Linux) file. In ADT, you can also access the updater by selecting Window > Android SDK Manager.
To run your application against different platform versions in the emulator, create an AVD for each platform version that you want to test. For more information about AVDs, see Creating and Managing Virtual Devices. If you are using a physical device for testing, ensure that you know the API Level of the Android platform it runs. See the table at the top of this document for a list of platform versions and their API Levels.
Reference documentation pages on the Android Developers site offer a "Filter by API Level" control in the top-right area of each page. You can use the control to show documentation only for parts of the API that are actually accessible to your application, based on the API Level that it specifies in the android:minSdkVersion attribute of its manifest file.
To use filtering, select the checkbox to enable filtering, just below the page search box. Then set the "Filter by API Level" control to the same API Level as specified by your application. Notice that APIs introduced in a later API Level are then grayed out and their content is masked, since they would not be accessible to your application.
Filtering by API Level in the documentation does not provide a view of what is new or introduced in each API Level — it simply provides a way to view the entire API associated with a given API Level, while excluding API elements introduced in later API Levels.
If you decide that you don't want to filter the API documentation, just disable the feature using the checkbox. By default, API Level filtering is disabled, so that you can view the full framework API, regardless of API Level.
Also note that the reference documentation for individual API elements specifies the API Level at which each element was introduced. The API Level for packages and classes is specified as "Since <api level>" at the top-right corner of the content area on each documentation page. The API Level for class members is specified in their detailed description headers, at the right margin.