Android Development-api Guide-<uses-sdk>

<uses-sdk>

English Original: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
Acquisition (update) Date: 2014-5-7
Moved from the original blog: http://blog.sina.com.cn/s/blog_48d491300100zmx9.html

In this article

1. What is the API level
2. API-level use in Android
3. Considerations for Development
   1. Forward compatibility for Applications
   2. Backward compatibility for Applications
   3. Select platform version and API level
   4. Declaring the lowest API level
   5. Testing for the high-version API level
4. Using the temporary API level
5. Filter reference documents based on API level

Google Play filtering mechanism

Google Play uses the attributes in manifest < uses-sdk > to filter the application and excludes devices that do not meet the requirements of the system version. Before setting this property, make sure you understand the Google Play filter completely

Grammar:

<android:minsdkversion= "integer"          android:targetsdkversion= "Integer"          android:maxsdkversion= "integer"/>

Included in:

<manifest>

Description

Used to indicate the compatibility of an application with one or more versions of the Android platform, expressed as an integer-type API level. The API level for application claims will be compared with a given Android system, and the API levels of different Android devices may vary.

Do not bother with the name (referred to as USES-SDK), this element is used to specify the API level, not the SDK (software Development Kit) or the version number of the Android platform. The API level is always represented by an integer value. The API level cannot be deduced from the corresponding Android version number (for example, it is neither the major version nor the major version number and the minor version number).

See the documentation for versioning your application.

Property:

android:minSdkVersion

integer value specifying the minimum API level required to run the application. If the system API level is below the value set by this property, the Android system will prevent users from installing the application. This property must be specified.

Reminder: If this property is not declared, the system assumes the default value is "1", which means that the application is compatible with all versions of Android. If the application is not compatible with all versions (for example, API level 3 is used to start the introduction of APIs), and is not declared correct android:minSdkVersion , then installed in a system below API Level 3, once in the run process to try to access the unavailable API, the application will crash 。 Therefore, make sure that the minSdkVersion correct API level is declared in the attribute.

android:targetSdkVersion

Integer value that specifies the target API level for the application. If this property is not set, the default value is equal to the given minSdkVersion .

This property informs the system that the application has been tested against this target version and does not enable any forward compatibility features related to this target version. The application is still able to run on an earlier (lowest minSdkVersion ) version of the system.

With the Android version updated, some features and even the appearance of the component will change. However, when the platform's API level is higher than the application claims targetSdkVersion , the compatibility feature is enabled and the application can still run as expected. targetSdkVersionYou can disable the compatibility feature by setting it to the desired platform version. For example, setting this value to be greater than or equal to "11" will allow the system to use the newly added default theme (Holo) on the application when running on Android 3.0 or later, and screen compatibility mode will be disabled on large screen devices (because API level 11 implies support for large screens).

Depending on the value set by this property, a number of compatibility features may be enabled on the system. There are quite a number of features that are described in the reference documentation Build.VERSION_CODES in the sub-version.

In order to be able to maintain the application with the release of the Android version, you should adjust the value of this property to match the latest API level in time, and then test the program thoroughly on the corresponding version of the platform.

Introduced at: API Level 4

android:maxSdkVersion

Integer value that specifies the highest API level that the application design can run.

In the Android 1.5, 1.6, 2.0, and 2.0.1 versions, this property value is checked when the application is re-verified after installing applications and system updates. In both cases, if the application's maxSdkVersion properties are smaller than the system's API level, the system blocks the installation of the program. In fact, when the application is re-verified after the system is updated, the application will be removed from the device.

To illustrate the impact of this property on the application after a system update, see the following example:

An application was declared in Manifest maxSdkVersion="5" and published on Google Play. One user has downloaded and installed this application, and his device is running Android 1.6 (API level 4). A few weeks later, the user upgraded the system to Android 2.0 (API Level 5) via the wireless system. After the upgrade is complete, the system checks the application maxSdkVersion and successfully re-verifies that the application works. But after a while, the device received another system update, this time upgrading to Android 2.0.1 (API level 6). The system is no longer able to re-verify the application after this update because the current system's API level (6) is already higher than the maximum version (5) supported by the application. The system will prevent users from using the application and will actually remove it from the device.

Warning: It is not recommended to declare this property. First, it is not necessary to use this property to prevent the application from being used on the new version of the Android platform. In theory, the new version of the platform is completely backwards fully compatible. The application should work properly on the new version of the platform, and the new version will not only provide the standard API, but also develop the best experience. Second, note that declaring this property on some occasions may cause the system to be removed after upgrading to a higher version of the API. Most devices receive periodic system updates over a wireless network, so you should consider the impact on your application before setting this property.

Introduced at: API Level 4

Higher versions of Android (higher than Android 2.0.1) are no longer checked and executed when installing or re-checking maxSdkVersionProperty. However, Google Play still uses this property as a filtering condition when it provides users with available downloads.

Introduced in:

API Level 1

What is the API level

The API level is an integer value that uniquely identifies the version of the API provided by a version of the Android platform.

The Android platform provides a complete set of APIs that applications can use to interact with the underlying system. This set of APIs consists of the following sections:

• Core packages and Classes
• Element and attribute declarations in XML format used in the Manifest file
• Elements and attributes in XML format used when declaring and accessing resources
• Some pre-Intent
• Permissions that the application can request and system presets

Each higher version of the Android platform will contain previous API updates.

The update mechanism of the API allows the new version of the API to be compatible with earlier versions. In other words, most of the API changes are new, or introduce new APIs, or replace the original functionality. As part of the API upgrade process, the old features that are replaced are considered obsolete but are not deleted. As a result, existing applications can still use these outdated features. In rare cases, some APIs may be modified or deleted, usually only to ensure the stability of the API and the security of the application or system. Early version?? The remainder of this API will be in the new version intact.

Each version of the API provided by the Android platform is identified by an integer value called "API level". Each version of the Android platform supports only one API level, although this implies support for all previous versions of the API level (up to API Level 1). The first version of the Android platform provides API level 1, and subsequent versions are incremented in turn.

The following table shows the supported API levels for each version of the Android platform. For a comparison of the number of Android devices in each version, see Platform version statistics.

Platform Version	API level	Version_code	Notes
Android 4.4	19	KITKAT	Characteristics
Android 4.3	18	JELLY_BEAN_MR2	Characteristics
Android 4.2, 4.2.2	17	JELLY_BEAN_MR1	Characteristics
Android 4.1, 4.1.1	16	JELLY_BEAN	Characteristics
Android 4.0.3, 4.0.4	15	ICE_CREAM_SANDWICH_MR1	Characteristics
Android 4.0, 4.0.1, 4.0.2	14	ICE_CREAM_SANDWICH
Android 3.2	13	HONEYCOMB_MR2
Android 3.1.x	12	HONEYCOMB_MR1	Characteristics
Android 3.0.x	11	HONEYCOMB	Characteristics
Android 2.3.4 Android 2.3.3	10	GINGERBREAD_MR1	Characteristics
Android 2.3.2 Android 2.3.1 Android 2.3	9	GINGERBREAD
Android 2.2.x	8	FROYO	Characteristics
Android 2.1.x	7	ECLAIR_MR1	Characteristics
Android 2.0.1	6	ECLAIR_0_1
Android 2.0	5	ECLAIR
Android 1.6	4	DONUT	Characteristics
Android 1.5	3	CUPCAKE	Characteristics
Android 1.1	2	BASE_1_1
Android 1.0	1	BASE

API-level use in Android

The API level plays a key role in ensuring the best experience for users and application developers:

• The Android platform can use it to describe the highest supported API versions.
• The application can use it to describe the required API version.
• The system can use it to verify that the application is installable on the user's device, and that an incompatible version of the application will not be installed.

Each version of the Android platform stores its own API-level alias within it.

The manifest element that the application can provide with the API- <uses-sdk> describes the lowest, highest API level that can function correctly, and the level of API that is expected to be supported. This element gives three key attributes:

• android:minSdkVersion-Indicates the lowest API level that the application can run. The default value is "1".
• android:targetSdkVersion-Indicates the level of API that is expected to run when the application is designed. In some cases, the application uses this property to use the manifest element or attribute defined in the target API level, not limited to content defined using the lowest API level.
• android:maxSdkVersion-Indicates the highest API level that the application can run. IMPORTANT: Please read the documentation before using this property <uses-sdk> .

For example, in order to specify the minimum API level required to run, an application should <uses-sdk> include attributes in its manifest element android:minSdkVersion . android:minSdkVersionvalue should be an integer that corresponds to the API level of the earliest Android version that the application can run.

When a user tries to install an application, or when the application is re-calibrated after a system upgrade, the Android system first checks the properties in the application manifest <uses-sdk> and compares its values to the API levels within the system. The installation of the application is allowed only if the following conditions are true:

• If a property is declared android:minSdkVersion , its value must be less than or equal to the current system's API level value. If not declared, the system assumes that the minimum API level required for the application to run is 1.
• If a property is declared android:maxSdkVersion , its value must be greater than or equal to the current system's API level value. If not declared, the system assumes that the application does not have a maximum API-level limit. For more information on how the system handles this property, read the documentation <uses-sdk> .

If a declaration is made in the application's manifest file, the <uses-sdk> element should look like the following:

< manifest>
<USES-SDK android:minsdkversion= "5"/>
...
</manifest>

Applications should android:minSdkVersion declare API levels in, primarily to tell the Android system that it will use APIs introduced at a given API level. If, for some reason, the application is installed on a platform with a lower API level, it crashes once it accesses the non-existent APIs. If the minimum API level required is higher than the platform version of the target device, the installation of the application is blocked, which prevents this from happening.

For example, the android.appwidget package was introduced at API Level 3. If an application uses this API, it must declare a android:minSdkVersion property of 3. This allows the application to be installed on Android 1.5 (API Level 3), Android 1.6 (API level 4) and other platforms, but not on Android 1.1 (API Level 2) and Android 1.0 (API level 1) platform On

For more information about specifying the API levels required by your application, see the section manifest files <uses-sdk> .

Considerations for Development

The following sections describe the API-level content that you should consider when developing your application.

Forward compatibility for Applications

Android apps are usually forward compatible with newer versions of the Android platform

Almost all API changes are incremental, so applications developed using a given version of the API (specified at the API level) are compatible with subsequent versions of Android and higher-level APIs. The application should be able to run on any high-version Android platform, unless it uses an API that has been removed for some reason.

Forward compatibility is important because many Android devices receive alerts for wireless (over-the-air, OTA) system updates. Users may be OK when installing and using the application, then receive OTA updates and upgrade to the new version of the Android platform. Once the upgrade is complete, the application will run in a new version of the environment, which also contains the API and system functionality required by the application.

In some cases, the changes that are hidden behind the API, such as changes at the bottom of the system, can have an impact on applications running in the new environment. As a developer, it is important to understand the look and behavior of applications in various system environments. To help you test your application on various versions of the Android platform, the Android SDK contains multiple versions of the platform for download. Each version of the platform contains a compatible system image that you can run on the appropriate version of the AVD (emulator) to test the application.

Backward compatibility for Applications

Android apps are not meant to be backwards compatible with Android platform versions earlier than the build environment.

Each new version of the Android platform may contain new APIs, such as providing new platform functionality, or replacing some of the existing APIs. Applications can use these new APIs in new and subsequent versions of the platform, and versions of updates can be reflected at the API level. Conversely, applications that use new APIs will not work on legacy platforms because the previous versions of the platform do not contain these new APIs.

While Android devices are unlikely to downgrade to previous versions of the system, you must be aware that many devices will still be running the older version of the system. Even those devices that receive OTA update messages, some of them will still delay the update even if they have not completed the update for a long time.

Select platform version and API level

When developing an application, you need to select a platform version to compile on this version of the Android platform. Typically, you should choose a minimum version that can be supported for compilation.

You can progressively decrement the target version and compile it to determine the minimum supported platform version. Once you have identified the lowest version, you should create an AVD of the appropriate version (i.e. API level) and test your application thoroughly. Make sure that the attribute is declared in the manifest of the application android:minSdkVersion and given the appropriate version of the API level.

Declaring the lowest API level

If your application uses the API or system features introduced by the latest version of the platform, you should set the android:minSdkVersion property to the API level for that version. This will ensure that users can install your application only on devices that are running the compatible version of Android that they need. This ensures that your application can be used properly on their devices.

If the application uses the API introduced by the latest version of the platform, but does not declare the android:minSdkVersion attribute, it will work correctly on the latest platform, but not on the previous version of the platform. In the latter case, once an application tries to access an API that does not exist on the old platform, it crashes.

Testing for the high-version API level

After the application has been compiled, you must test on the android:minSdkVersion version of the property setting. Please create an AVD with the appropriate version to complete the test. In addition, to ensure forward compatibility, you should also run and test the application on all versions that are above the required API level.

The Android SDK includes a multi-version platform including the latest version for use, and an upgrade tool to download the other versions you need.

To use the upgrade tool, use the android command-line tool, which is located in the <sdk>/tools directory. You can execute android sdk the command to launch the SDK upgrade tool, or you can simply double-click Android.bat (under Windows) or Android (OS x/linux) files. In ADT, you can also choose menu Window > Android SDK Manager to access the upgrade tool.

To enable the application to run on multiple versions of the emulator, create an AVD device for each version that you want to test. For more information about AVD, see Creating and managing emulators. If you are testing with a physical device, confirm the API level of its Android platform. See the platform version and API level comparison table at the beginning of this article.

Using the temporary API level

Sometimes, there may be an "early preview" (Early look) version of the Android platform SDK. Although the API may not be the final version at this point, the API level of such a platform will not be set for development on this release. You must swap the provisional API level for this version of the platform in manifest to establish the application that corresponds to this version. The temporary API level is not an integer, but rather a string name that represents the version of the unpublished platform. The temporary API level for an early preview version is set in the release notes and is case-sensitive.

The purpose of the temporary API level is to prevent developers from inadvertently publishing or accidentally installing applications that were developed based on the early preview version of the API, which may not run stably on the final system.

The temporary API level is only valid when using an earlier preview version of the SDK and can only be run in the emulator. Applications that use the temporary API level will never be installed on Android devices. After the final release, you must replace all temporary API levels in manifest with the actual API level values of the final platform.

Filter reference documents based on API level

In the upper-right corner of the reference document page of the Android developers Web site, there is an option to "Filter by API levels" (the "Filter by API level"). ( Translator Note : verified, this option is currently on the left side of the page, you can directly drop down to select each API level.) With this option, you can display only the portion of the API document that the application actually uses, as determined by the android:minSdkVersion API level specified in the attribute values in the Manifest file.

To use the filter feature, select the check box below the search box. ( Translator Note : The check box was not found, perhaps the document was not updated.) then set the Filter by API level option to the API levels specified by the application. As you can see, the content of these new APIs is marked dimmed because the application cannot access the API that was introduced after the specified level.

The ability to filter at the API level does not provide a new page for each API level addition, it simply gives a way to fully present the content of a certain level of API and removes the API content introduced in subsequent releases.

If you do not need to filter the API documentation, simply disable it by ticking the box. API level filtering is disabled by default, so you can see all the APIs without having to care about the API level.

It is also important to note that each individual API Reference Document page indicates the level at which the API was introduced. The API levels for packages and classes are described in the "Since <api level>" section in the upper-right corner of each document page. The API level of a class member is described in the upper-right part of its detailed information.

Android Development-api Guide-<uses-sdk>