uses-sdk-element.jd revision d4eb682b5fa06f476d6f091b7df1213e7f1e07f8
1page.title=<uses-sdk> 2parent.title=The AndroidManifest.xml File 3parent.link=manifest-intro.html 4@jd:body 5 6<dl class="xml"> 7<dt>syntax:</dt> 8<dd><pre> 9<uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>" 10 android:<a href="#target">targetSdkVersion</a>="<i>integer</i>" 11 android:<a href="#max">maxSdkVersion</a>="<i>integer</i>" /></pre></dd> 12 13<dt>contained in:</dt> 14<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> 15 16<dt>description:</dt> 17<dd>Lets you express an application's compatibility with one or more versions of the Android platform, 18by means of an API Level integer. The API Level expressed by an application will be compared to the 19API Level of a given Android system, which may vary among different Android devices. 20</p> 21 22<p>Despite its name, this element is used to specify the API Level, <em>not</em> 23the version number of the SDK (software development kit) or Android platform. 24The API Level is always a single integer. You cannot derive the API Level from 25its associated Android version number (for example, it is not the same as the 26major version or the sum of the major and minor versions).</p> 27 28<p>For more information, read about 29<a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and 30<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>. 31</p></dd> 32 33 <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> 34 <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> 35 <div id="qv-sub-rule"> 36 <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> 37 <p style="color:#669999;">Android Market and <uses-sdk> attributes</p> 38 <p>Android Market filters the applications that are visible to users, so 39that users can only see and download applications that are compatible with their 40devices. One of the ways Market filters applications is by Android 41version-compatibility. To do this, Market checks the <code><uses-sdk></code> 42attributes in each application's manifest to establish its version-compatibility 43range, then shows or hides the application based on a comparison with the API 44Level of the user's Android system version. For more information, see <a 45href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> 46 </div> 47</div> 48 49<dt>attributes:</dt> 50 51<dd> 52<dl class="attr"> 53 <dt><a name="min"></a>{@code android:minSdkVersion}</dt> 54 <dd>An integer designating the minimum API Level required 55 for the application to run. The Android system will prevent the user from installing 56 the application if the system's API Level is lower than the value specified in 57 this attribute. You should always declare this attribute. 58 59 <p class="caution"><strong>Caution:</strong> If you do not declare this 60 attribute, the system assumes a default value of "1", which indicates that your 61 application is compatible with all versions of Android. If your application is 62 <em>not</em> compatible with all versions (for instance, it uses APIs introduced 63 in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, 64 then when installed on a system with an API Level less than 3, the application 65 will crash during runtime when attempting to access the unavailable APIs. For 66 this reason, be certain to declare the appropriate API Level in the 67 <code>minSdkVersion</code> attribute.</p> 68 </dd> 69 70 <dt><a name="target"></a>{@code android:targetSdkVersion}</dt> 71 <dd>An integer designating the API Level that the application targets. If not set, the default 72value equals that given to {@code minSdkVersion}. 73 74 <p>This attribute informs the system that you have tested against the target version and the 75system should not enable any compatibility behaviors to maintain your app's forward-compatibility 76with the target version. The application is still able to run on older versions (down to {@code 77minSdkVersion}).</p> 78 79 <p>As Android evolves with each new version, some behaviors and even appearances might change. 80However, if the API level of the platform is higher than the version declared by your app's {@code 81targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app 82continues to work the way you expect. You can disable such compatibility 83behaviors by specifying {@code targetSdkVersion} to match the API 84level of the platform on which it's running. For example, setting this value to "11" or higher 85allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or 86higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen 87compatibility mode</a> when running on larger screens (because support for API level 11 implicitly 88supports larger screens).</p> 89 90 <p>There are many compatibility behaviors that the system may enable based on the value you set 91for this attribute. Several of these behaviors are described by the corresponding platform versions 92in the {@link android.os.Build.VERSION_CODES} reference.</p> 93 94 <p>To maintain your application along with each Android release, you should increase 95the value of this attribute to match the latest API level, then thoroughly test your application on 96the corresponding platform version.</p> 97 98 <p>Introduced in: API Level 4</p> 99 </dd> 100 101 <dt><a name="max"></a>{@code android:maxSdkVersion}</dt> 102 <dd>An integer designating the maximum API Level on which the application is 103 designed to run. 104 105 <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this 106 attribute when installing an application and when re-validating the application 107 after a system update. In either case, if the application's 108 <code>maxSdkVersion</code> attribute is lower than the API Level used by 109 the system itself, then the system will not allow the application to be 110 installed. In the case of re-validation after system update, this effectively 111 removes your application from the device. 112 113 <p>To illustrate how this attribute can affect your application after system 114 updates, consider the following example: </p> 115 116 <p>An application declaring <code>maxSdkVersion="5"</code> in its 117 manifest is published on Android Market. A user whose device is running Android 118 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user 119 receives an over-the-air system update to Android 2.0 (API Level 5). After the 120 update is installed, the system checks the application's 121 <code>maxSdkVersion</code> and successfully re-validates it. The 122 application functions as normal. However, some time later, the device receives 123 another system update, this time to Android 2.0.1 (API Level 6). After the 124 update, the system can no longer re-validate the application because the system's 125 own API Level (6) is now higher than the maximum supported by the application 126 (5). The system prevents the application from being visible to the user, in 127 effect removing it from the device.</p> 128 129 <p class="warning"><strong>Warning:</strong> Declaring this attribute is not 130 recommended. First, there is no need to set the attribute as means of blocking 131 deployment of your application onto new versions of the Android platform as they 132 are released. By design, new versions of the platform are fully 133 backward-compatible. Your application should work properly on new versions, 134 provided it uses only standard APIs and follows development best practices. 135 Second, note that in some cases, declaring the attribute can <strong>result in 136 your application being removed from users' devices after a system 137 update</strong> to a higher API Level. Most devices on which your application 138 is likely to be installed will receive periodic system updates over the air, so 139 you should consider their effect on your application before setting this 140 attribute.</p> 141 142 <p style="margin-bottom:1em;">Introduced in: API Level 4</p> 143 144 <div class="special">Future versions of Android (beyond Android 2.0.1) will no 145longer check or enforce the <code>maxSdkVersion</code> attribute during 146installation or re-validation. Android Market will continue to use the attribute 147as a filter, however, when presenting users with applications available for 148download. </div> 149 </dd> 150 151 152</dl></dd> 153 154<!-- ##api level indication## --> 155<dt>introduced in:</dt> 156<dd>API Level 1</dd> 157 158</dl> 159