blob: 99c91f6862b65d311e1970150495c00f9be795ac [file] [log] [blame]
parent.title=The AndroidManifest.xml File
<dl class="xml">
&lt;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>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<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>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>.
<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 &lt;uses-sdk&gt; 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>&lt;uses-sdk&gt;</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>
<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>
<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
<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>
<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
<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>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>