| page.title=<uses-sdk> |
| parent.title=The AndroidManifest.xml File |
| parent.link=manifest-intro.html |
| @jd:body |
| |
| <dl class="xml"> |
| <dt>syntax:</dt> |
| <dd><pre> |
| <uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>" |
| android:<a href="#target">targetSdkVersion</a>="<i>integer</i>" |
| android:<a href="#max">maxSdkVersion</a>="<i>integer</i>" /></pre></dd> |
| |
| <dt>contained in:</dt> |
| <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> |
| |
| <dt>description:</dt> |
| <dd>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. |
| </p> |
| |
| <p>Despite its name, this element is used to specify the API Level, <em>not</em> |
| 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).</p> |
| |
| <p>For more information, read about |
| <a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and |
| <a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>. |
| </p></dd> |
| |
| <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> |
| <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> |
| <div id="qv-sub-rule"> |
| <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> |
| <p style="color:#669999;">Android Market and <uses-sdk> attributes</p> |
| <p>Android Market filters the applications that are visible to users, so |
| that users can only see and download applications that are compatible with their |
| devices. One of the ways Market filters applications is by Android |
| version-compatibility. To do this, Market checks the <code><uses-sdk></code> |
| attributes in each application's manifest to establish its version-compatibility |
| range, then shows or hides the application based on a comparison with the API |
| Level of the user's Android system version. For more information, see <a |
| href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> |
| </div> |
| </div> |
| |
| <dt>attributes:</dt> |
| |
| <dd> |
| <dl class="attr"> |
| <dt><a name="min"></a>{@code android:minSdkVersion}</dt> |
| <dd>An integer designating the minimum API Level required |
| for the application to run. The Android system will prevent the user from installing |
| the application if the system's API Level is lower than the value specified in |
| this attribute. You should always declare this attribute. |
| |
| <p class="caution"><strong>Caution:</strong> 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 |
| <em>not</em> compatible with all versions (for instance, it uses APIs introduced |
| in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, |
| 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 |
| <code>minSdkVersion</code> attribute.</p> |
| </dd> |
| |
| <dt><a name="target"></a>{@code android:targetSdkVersion}</dt> |
| <dd>An integer designating the API Level that the application targets. If not set, the default |
| value equals that given to {@code minSdkVersion}. |
| |
| <p>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 {@code |
| minSdkVersion}).</p> |
| |
| <p>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 {@code |
| 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 {@code 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 <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen |
| compatibility mode</a> when running on larger screens (because support for API level 11 implicitly |
| supports larger screens).</p> |
| |
| <p>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 {@link android.os.Build.VERSION_CODES} reference.</p> |
| |
| <p>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.</p> |
| |
| <p>Introduced in: API Level 4</p> |
| </dd> |
| |
| <dt><a name="max"></a>{@code android:maxSdkVersion}</dt> |
| <dd>An integer designating the maximum API Level on which the application is |
| designed to run. |
| |
| <p>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 |
| <code>maxSdkVersion</code> 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. |
| |
| <p>To illustrate how this attribute can affect your application after system |
| updates, consider the following example: </p> |
| |
| <p>An application declaring <code>maxSdkVersion="5"</code> in its |
| manifest is published on Android Market. 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 |
| <code>maxSdkVersion</code> 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.</p> |
| |
| <p class="warning"><strong>Warning:</strong> 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 <strong>result in |
| your application being removed from users' devices after a system |
| update</strong> 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.</p> |
| |
| <p style="margin-bottom:1em;">Introduced in: API Level 4</p> |
| |
| <div class="special">Future versions of Android (beyond Android 2.0.1) will no |
| longer check or enforce the <code>maxSdkVersion</code> attribute during |
| installation or re-validation. Android Market will continue to use the attribute |
| as a filter, however, when presenting users with applications available for |
| download. </div> |
| </dd> |
| |
| |
| </dl></dd> |
| |
| <!-- ##api level indication## --> |
| <dt>introduced in:</dt> |
| <dd>API Level 1</dd> |
| |
| </dl> |