1page.title=<uses-sdk> 2page.tags=api levels,sdk version,minsdkversion,targetsdkversion,maxsdkversion 3@jd:body 4 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9<h2>In this document</h2> 10<ol> 11 <li><a href="#ApiLevels">What is API Level?</a></li> 12 <li><a href="#uses">Uses of API Level in Android</a></li> 13 <li><a href="#considerations">Development Considerations</a> 14 <ol> 15 <li><a href="#fc">Application forward compatibility</a></li> 16 <li><a href="#bc">Application backward compatibility</a></li> 17 <li><a href="#platform">Selecting a platform version and API Level</a></li> 18 <li><a href="#apilevel">Declaring a minimum API Level</a></li> 19 <li><a href="#testing">Testing against higher API Levels</a></li> 20 </ol> 21 </li> 22 <li><a href="#filtering">Filtering the Reference Documentation by API Level</a></li> 23</ol> 24</div> 25</div> 26 27<div class="sidebox-wrapper"> 28<div class="sidebox"> 29 <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> 30 <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> 31 <p style="padding-top:1em;">Google Play uses the <code><uses-sdk></code> 32 attributes declared in your app manifest to filter your app from devices 33 that do not meet it's platform version requirements. Before setting these 34 attributes, make sure that you understand 35 <a href="{@docRoot}google/play/filters.html">Google Play filters</a>. </p> 36 </div> 37</div> 38 39<dl class="xml"> 40<dt>syntax:</dt> 41<dd><pre> 42<uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>" 43 android:<a href="#target">targetSdkVersion</a>="<i>integer</i>" 44 android:<a href="#max">maxSdkVersion</a>="<i>integer</i>" /></pre></dd> 45 46<dt>contained in:</dt> 47<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> 48 49<dt>description:</dt> 50<dd itemprop="description"><p> Lets you express an application's compatibility with one or more versions of the Android platform, 51by means of an API Level integer. The API Level expressed by an application will be compared to the 52API Level of a given Android system, which may vary among different Android devices. 53</p> 54 55<p>Despite its name, this element is used to specify the API Level, <em>not</em> 56the version number of the SDK (software development kit) or Android platform. 57The API Level is always a single integer. You cannot derive the API Level from 58its associated Android version number (for example, it is not the same as the 59major version or the sum of the major and minor versions).</p> 60 61<p>Also read the document about 62<a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a>. 63</p></dd> 64 65<dt>attributes:</dt> 66 67<dd> 68<dl class="attr"> 69 <dt><a name="min"></a>{@code android:minSdkVersion}</dt> 70 <dd>An integer designating the minimum API Level required 71 for the application to run. The Android system will prevent the user from installing 72 the application if the system's API Level is lower than the value specified in 73 this attribute. You should always declare this attribute. 74 75 <p class="caution"><strong>Caution:</strong> If you do not declare this 76 attribute, the system assumes a default value of "1", which indicates that your 77 application is compatible with all versions of Android. If your application is 78 <em>not</em> compatible with all versions (for instance, it uses APIs introduced 79 in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, 80 then when installed on a system with an API Level less than 3, the application 81 will crash during runtime when attempting to access the unavailable APIs. For 82 this reason, be certain to declare the appropriate API Level in the 83 <code>minSdkVersion</code> attribute.</p> 84 </dd> 85 86 <dt><a name="target"></a>{@code android:targetSdkVersion}</dt> 87 <dd>An integer designating the API Level that the application targets. If not set, the default 88value equals that given to {@code minSdkVersion}. 89 90 <p>This attribute informs the system that you have tested against the target version and the 91system should not enable any compatibility behaviors to maintain your app's forward-compatibility 92with the target version. The application is still able to run on older versions (down to {@code 93minSdkVersion}).</p> 94 95 <p>As Android evolves with each new version, some behaviors and even appearances might change. 96However, if the API level of the platform is higher than the version declared by your app's {@code 97targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app 98continues to work the way you expect. You can disable such compatibility 99behaviors by specifying {@code targetSdkVersion} to match the API 100level of the platform on which it's running. For example, setting this value to "11" or higher 101allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or 102higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen 103compatibility mode</a> when running on larger screens (because support for API level 11 implicitly 104supports larger screens).</p> 105 106 <p>There are many compatibility behaviors that the system may enable based on the value you set 107for this attribute. Several of these behaviors are described by the corresponding platform versions 108in the {@link android.os.Build.VERSION_CODES} reference.</p> 109 110 <p>To maintain your application along with each Android release, you should increase 111the value of this attribute to match the latest API level, then thoroughly test your application on 112the corresponding platform version.</p> 113 114 <p>Introduced in: API Level 4</p> 115 </dd> 116 117 <dt><a name="max"></a>{@code android:maxSdkVersion}</dt> 118 <dd>An integer designating the maximum API Level on which the application is 119 designed to run. 120 121 <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this 122 attribute when installing an application and when re-validating the application 123 after a system update. In either case, if the application's 124 <code>maxSdkVersion</code> attribute is lower than the API Level used by 125 the system itself, then the system will not allow the application to be 126 installed. In the case of re-validation after system update, this effectively 127 removes your application from the device. 128 129 <p>To illustrate how this attribute can affect your application after system 130 updates, consider the following example: </p> 131 132 <p>An application declaring <code>maxSdkVersion="5"</code> in its 133 manifest is published on Google Play. A user whose device is running Android 134 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user 135 receives an over-the-air system update to Android 2.0 (API Level 5). After the 136 update is installed, the system checks the application's 137 <code>maxSdkVersion</code> and successfully re-validates it. The 138 application functions as normal. However, some time later, the device receives 139 another system update, this time to Android 2.0.1 (API Level 6). After the 140 update, the system can no longer re-validate the application because the system's 141 own API Level (6) is now higher than the maximum supported by the application 142 (5). The system prevents the application from being visible to the user, in 143 effect removing it from the device.</p> 144 145 <p class="warning"><strong>Warning:</strong> Declaring this attribute is not 146 recommended. First, there is no need to set the attribute as means of blocking 147 deployment of your application onto new versions of the Android platform as they 148 are released. By design, new versions of the platform are fully 149 backward-compatible. Your application should work properly on new versions, 150 provided it uses only standard APIs and follows development best practices. 151 Second, note that in some cases, declaring the attribute can <strong>result in 152 your application being removed from users' devices after a system 153 update</strong> to a higher API Level. Most devices on which your application 154 is likely to be installed will receive periodic system updates over the air, so 155 you should consider their effect on your application before setting this 156 attribute.</p> 157 158 <p style="margin-bottom:1em;">Introduced in: API Level 4</p> 159 160 <div class="special">Future versions of Android (beyond Android 2.0.1) will no 161longer check or enforce the <code>maxSdkVersion</code> attribute during 162installation or re-validation. Google Play will continue to use the attribute 163as a filter, however, when presenting users with applications available for 164download. </div> 165 </dd> 166 167 168</dl></dd> 169 170<!-- ##api level indication## --> 171<dt>introduced in:</dt> 172<dd>API Level 1</dd> 173 174</dl> 175 176 177 178 179 180<!--- CONTENT FROM OLD API LEVEL DOC ----> 181 182 183 184 185<h2 id="ApiLevels">What is API Level?</h2> 186 187<p>API Level is an integer value that uniquely identifies the framework API 188revision offered by a version of the Android platform.</p> 189 190<p>The Android platform provides a framework API that applications can use to 191interact with the underlying Android system. The framework API consists of:</p> 192 193<ul> 194<li>A core set of packages and classes</li> 195<li>A set of XML elements and attributes for declaring a manifest file</li> 196<li>A set of XML elements and attributes for declaring and accessing resources</li> 197<li>A set of Intents</li> 198<li>A set of permissions that applications can request, as well as permission 199enforcements included in the system</li> 200</ul> 201 202<p>Each successive version of the Android platform can include updates to the 203Android application framework API that it delivers. </p> 204 205<p>Updates to the framework API are designed so that the new API remains 206compatible with earlier versions of the API. That is, most changes in the API 207are additive and introduce new or replacement functionality. As parts of the API 208are upgraded, the older replaced parts are deprecated but are not removed, so 209that existing applications can still use them. In a very small number of cases, 210parts of the API may be modified or removed, although typically such changes are 211only needed to ensure API robustness and application or system security. All 212other API parts from earlier revisions are carried forward without 213modification.</p> 214 215<p>The framework API that an Android platform delivers is specified using an 216integer identifier called "API Level". Each Android platform version supports 217exactly one API Level, although support is implicit for all earlier API Levels 218(down to API Level 1). The initial release of the Android platform provided 219API Level 1 and subsequent releases have incremented the API Level.</p> 220 221<p>The table below specifies the API Level supported by each version of the 222Android platform. For information about the relative numbers of devices that 223are running each version, see the <a href="{@docRoot}about/dashboards/index.html">Platform 224Versions dashboards page</a>.</p> 225 226<table> 227 <tr><th>Platform Version</th><th>API Level</th><th>VERSION_CODE</th><th>Notes</th></tr> 228 229 <tr><td>Android 6.0</td> 230 <td><a href="{@docRoot}sdk/api_diff/23/changes.html" title="Diff Report">23</a></td> 231 <td>{@link android.os.Build.VERSION_CODES#M}</td> 232 <td><a href="{@docRoot}preview/api-overview.html">API Changes</a></td></tr> 233 234 <tr><td><a href="{@docRoot}about/versions/android-5.1.html">Android 5.1</a></td> 235 <td><a href="{@docRoot}sdk/api_diff/22/changes.html" title="Diff Report">22</a></td> 236 <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1}</td> 237 <td rowspan="2"><a href="{@docRoot}about/versions/lollipop.html">Platform 238Highlights</a></td></tr> 239 240 <tr><td><a href="{@docRoot}about/versions/android-5.0.html">Android 5.0</a></td> 241 <td><a href="{@docRoot}sdk/api_diff/21/changes.html" title="Diff Report">21</a></td> 242 <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP}</td> 243 </tr> 244 245 <tr><td style="color:#bbb">Android 4.4W</td> 246 <td><a href="{@docRoot}sdk/api_diff/20/changes.html" title="Diff Report">20</a></td> 247 <td>{@link android.os.Build.VERSION_CODES#KITKAT_WATCH}</td> 248 <td style="color:#bbb">KitKat for Wearables Only</td></tr> 249 250 <tr><td><a href="{@docRoot}about/versions/android-4.4.html">Android 4.4</a></td> 251 <td><a href="{@docRoot}sdk/api_diff/19/changes.html" title="Diff Report">19</a></td> 252 <td>{@link android.os.Build.VERSION_CODES#KITKAT}</td> 253 <td><a href="{@docRoot}about/versions/kitkat.html">Platform 254Highlights</a></td></tr> 255 256 <tr><td><a href="{@docRoot}about/versions/android-4.3.html">Android 4.3</a></td> 257 <td><a href="{@docRoot}sdk/api_diff/18/changes.html" title="Diff Report">18</a></td> 258 <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}</td> 259 <td><a href="{@docRoot}about/versions/jelly-bean.html">Platform 260Highlights</a></td></tr> 261 262 <tr><td><a href="{@docRoot}about/versions/android-4.2.html">Android 4.2, 4.2.2</a></td> 263 <td><a href="{@docRoot}sdk/api_diff/17/changes.html" title="Diff Report">17</a></td> 264 <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}</td> 265 <td><a href="{@docRoot}about/versions/jelly-bean.html#android-42">Platform 266Highlights</a></td></tr> 267 268 <tr><td><a href="{@docRoot}about/versions/android-4.1.html">Android 4.1, 4.1.1</a></td> 269 <td><a href="{@docRoot}sdk/api_diff/16/changes.html" title="Diff Report">16</a></td> 270 <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN}</td> 271 <td><a href="{@docRoot}about/versions/jelly-bean.html#android-41">Platform 272Highlights</a></td></tr> 273 274 <tr><td><a href="{@docRoot}about/versions/android-4.0.3.html">Android 4.0.3, 4.0.4</a></td> 275 <td><a href="{@docRoot}sdk/api_diff/15/changes.html" title="Diff Report">15</a></td> 276 <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1}</td> 277 <td rowspan="2"><a href="{@docRoot}about/versions/android-4.0-highlights.html">Platform 278Highlights</a></td></tr> 279 280 <tr><td><a href="{@docRoot}about/versions/android-4.0.html">Android 4.0, 4.0.1, 4.0.2</a></td> 281 <td><a href="{@docRoot}sdk/api_diff/14/changes.html" title="Diff Report">14</a></td> 282 <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}</td> 283 </tr> 284 285 <tr><td><a href="{@docRoot}about/versions/android-3.2.html">Android 3.2</a></td> 286 <td><a href="{@docRoot}sdk/api_diff/13/changes.html" title="Diff Report">13</a></td> 287 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}</td> 288 <td><!-- <a href="{@docRoot}about/versions/android-3.2-highlights.html">Platform 289Highlights</a>--></td></tr> 290 291 <tr><td><a href="{@docRoot}about/versions/android-3.1.html">Android 3.1.x</a></td> 292 <td><a href="{@docRoot}sdk/api_diff/12/changes.html" title="Diff Report">12</a></td> 293 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR1}</td> 294 <td><a href="{@docRoot}about/versions/android-3.1-highlights.html">Platform Highlights</a></td></tr> 295 296 <tr><td><a href="{@docRoot}about/versions/android-3.0.html">Android 3.0.x</a></td> 297 <td><a href="{@docRoot}sdk/api_diff/11/changes.html" title="Diff Report">11</a></td> 298 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB}</td> 299 <td><a href="{@docRoot}about/versions/android-3.0-highlights.html">Platform Highlights</a></td></tr> 300 301 <tr><td><a href="{@docRoot}about/versions/android-2.3.3.html">Android 2.3.4<br>Android 2.3.3</a></td> 302 <td><a href="{@docRoot}sdk/api_diff/10/changes.html" title="Diff Report">10</a></td> 303 <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD_MR1}</td> 304 <td rowspan="2"><a href="{@docRoot}about/versions/android-2.3-highlights.html">Platform 305Highlights</a></td></tr> 306 307 <tr><td><a href="{@docRoot}about/versions/android-2.3.html">Android 2.3.2<br>Android 2.3.1<br> 308 Android 2.3</a></td> 309 <td><a href="{@docRoot}sdk/api_diff/9/changes.html" title="Diff Report">9</a></td> 310 <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD}</td> 311 </tr> 312 313 <tr><td><a href="{@docRoot}about/versions/android-2.2.html">Android 2.2.x</a></td> 314 <td ><a href="{@docRoot}sdk/api_diff/8/changes.html" title="Diff Report">8</a></td> 315 <td>{@link android.os.Build.VERSION_CODES#FROYO}</td> 316 <td><a href="{@docRoot}about/versions/android-2.2-highlights.html">Platform Highlights</a></td></tr> 317 318 <tr><td><a href="{@docRoot}about/versions/android-2.1.html">Android 2.1.x</a></td> 319 <td><a href="{@docRoot}sdk/api_diff/7/changes.html" title="Diff Report">7</a></td> 320 <td>{@link android.os.Build.VERSION_CODES#ECLAIR_MR1}</td> 321 <td rowspan="3" ><a href="{@docRoot}about/versions/android-2.0-highlights.html">Platform 322Highlights</a></td></tr> 323 324 <tr><td><a href="{@docRoot}about/versions/android-2.0.1.html">Android 2.0.1</a></td> 325 <td><a href="{@docRoot}sdk/api_diff/6/changes.html" title="Diff Report">6</a></td> 326 <td>{@link android.os.Build.VERSION_CODES#ECLAIR_0_1}</td> 327 </tr> 328 329 <tr><td><a href="{@docRoot}about/versions/android-2.0.html">Android 2.0</a></td> 330 <td><a href="{@docRoot}sdk/api_diff/5/changes.html" title="Diff Report">5</a></td> 331 <td>{@link android.os.Build.VERSION_CODES#ECLAIR}</td> 332 </tr> 333 334 <tr><td><a href="{@docRoot}about/versions/android-1.6.html">Android 1.6</a></td> 335 <td><a href="{@docRoot}sdk/api_diff/4/changes.html" title="Diff Report">4</a></td> 336 <td>{@link android.os.Build.VERSION_CODES#DONUT}</td> 337 <td><a href="{@docRoot}about/versions/android-1.6-highlights.html">Platform Highlights</a></td></tr> 338 339 <tr><td><a href="{@docRoot}about/versions/android-1.5.html">Android 1.5</a></td> 340 <td><a href="{@docRoot}sdk/api_diff/3/changes.html" title="Diff Report">3</a></td> 341 <td>{@link android.os.Build.VERSION_CODES#CUPCAKE}</td> 342 <td><a href="{@docRoot}about/versions/android-1.5-highlights.html">Platform Highlights</a></td></tr> 343 344 <tr><td><a href="{@docRoot}about/versions/android-1.1.html">Android 1.1</a></td> 345 <td>2</td> 346 <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> 347 348 <tr><td>Android 1.0</td> 349 <td>1</td> 350 <td>{@link android.os.Build.VERSION_CODES#BASE}</td> 351 <td></td></tr> 352</table> 353 354 355<h2 id="uses">Uses of API Level in Android</h2> 356 357<p>The API Level identifier serves a key role in ensuring the best possible 358experience for users and application developers: 359 360<ul> 361<li>It lets the Android platform describe the maximum framework API revision 362that it supports</li> 363<li>It lets applications describe the framework API revision that they 364require</li> 365<li>It lets the system negotiate the installation of applications on the user's 366device, such that version-incompatible applications are not installed.</li> 367</ul> 368 369<p>Each Android platform version stores its API Level identifier internally, in 370the Android system itself. </p> 371 372<p>Applications can use a manifest element provided by the framework API — 373<code><uses-sdk></code> — to describe the minimum and maximum API 374Levels under which they are able to run, as well as the preferred API Level that 375they are designed to support. The element offers three key attributes:</p> 376 377<ul> 378<li><code>android:minSdkVersion</code> — Specifies the minimum API Level 379on which the application is able to run. The default value is "1".</li> 380<li><code>android:targetSdkVersion</code> — Specifies the API Level 381on which the application is designed to run. In some cases, this allows the 382application to use manifest elements or behaviors defined in the target 383API Level, rather than being restricted to using only those defined 384for the minimum API Level.</li> 385<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level 386on which the application is able to run. <strong>Important:</strong> Please read the <a 387href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 388documentation before using this attribute. </li> 389</ul> 390 391<p>For example, to specify the minimum system API Level that an application 392requires in order to run, the application would include in its manifest a 393<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> 394attribute. The value of <code>android:minSdkVersion</code> would be the integer 395corresponding to the API Level of the earliest version of the Android platform 396under which the application can run. </p> 397 398<p>When the user attempts to install an application, or when revalidating an 399appplication after a system update, the Android system first checks the 400<code><uses-sdk></code> attributes in the application's manifest and 401compares the values against its own internal API Level. The system allows the 402installation to begin only if these conditions are met:</p> 403 404<ul> 405<li>If a <code>android:minSdkVersion</code> attribute is declared, its value 406must be less than or equal to the system's API Level integer. If not declared, 407the system assumes that the application requires API Level 1. </li> 408<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value 409must be equal to or greater than the system's API Level integer. 410If not declared, the system assumes that the application 411has no maximum API Level. Please read the <a 412href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 413documentation for more information about how the system handles this attribute.</li> 414</ul> 415 416<p>When declared in an application's manifest, a <code><uses-sdk></code> 417element might look like this: </p> 418 419<pre><manifest> 420 <uses-sdk android:minSdkVersion="5" /> 421 ... 422</manifest></pre> 423 424<p>The principal reason that an application would declare an API Level in 425<code>android:minSdkVersion</code> is to tell the Android system that it is 426using APIs that were <em>introduced</em> in the API Level specified. If the 427application were to be somehow installed on a platform with a lower API Level, 428then it would crash at run-time when it tried to access APIs that don't exist. 429The system prevents such an outcome by not allowing the application to be 430installed if the lowest API Level it requires is higher than that of the 431platform version on the target device.</p> 432 433<p>For example, the {@link android.appwidget} package was introduced with API 434Level 3. If an application uses that API, it must declare a 435<code>android:minSdkVersion</code> attribute with a value of "3". The 436application will then be installable on platforms such as Android 1.5 (API Level 4373) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and 438Android 1.0 platforms (API Level 1).</p> 439 440<p>For more information about how to specify an application's API Level 441requirements, see the <a 442href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 443 section of the manifest file documentation.</p> 444 445 446<h2 id="considerations">Development Considerations</h2> 447 448<p>The sections below provide information related to API level that you should 449consider when developing your application.</p> 450 451<h3 id="fc">Application forward compatibility</h3> 452 453<p>Android applications are generally forward-compatible with new versions of 454the Android platform.</p> 455 456<p>Because almost all changes to the framework API are additive, an Android 457application developed using any given version of the API (as specified by its 458API Level) is forward-compatible with later versions of the Android platform and 459higher API levels. The application should be able to run on all later versions 460of the Android platform, except in isolated cases where the application uses a 461part of the API that is later removed for some reason. </p> 462 463<p>Forward compatibility is important because many Android-powered devices 464receive over-the-air (OTA) system updates. The user may install your 465application and use it successfully, then later receive an OTA update to a new 466version of the Android platform. Once the update is installed, your application 467will run in a new run-time version of the environment, but one that has the API 468and system capabilities that your application depends on. </p> 469 470<p>In some cases, changes <em>below</em> the API, such those in the underlying 471system itself, may affect your application when it is run in the new 472environment. For that reason it's important for you, as the application 473developer, to understand how the application will look and behave in each system 474environment. To help you test your application on various versions of the Android 475platform, the Android SDK includes multiple platforms that you can download. 476Each platform includes a compatible system image that you can run in an AVD, to 477test your application. </p> 478 479<h3 id="bc">Application backward compatibility</h3> 480 481<p>Android applications are not necessarily backward compatible with versions of 482the Android platform older than the version against which they were compiled. 483</p> 484 485<p>Each new version of the Android platform can include new framework APIs, such 486as those that give applications access to new platform capabilities or replace 487existing API parts. The new APIs are accessible to applications when running on 488the new platform and, as mentioned above, also when running on later versions of 489the platform, as specified by API Level. Conversely, because earlier versions of 490the platform do not include the new APIs, applications that use the new APIs are 491unable to run on those platforms.</p> 492 493<p>Although it's unlikely that an Android-powered device would be downgraded to 494a previous version of the platform, it's important to realize that there are 495likely to be many devices in the field that run earlier versions of the 496platform. Even among devices that receive OTA updates, some might lag and 497might not receive an update for a significant amount of time. </p> 498 499<h3 id="platform">Selecting a platform version and API Level</h3> 500 501<p>When you are developing your application, you will need to choose 502the platform version against which you will compile the application. In 503general, you should compile your application against the lowest possible 504version of the platform that your application can support. 505 506<p>You can determine the lowest possible platform version by compiling the 507application against successively lower build targets. After you determine the 508lowest version, you should create an AVD using the corresponding platform 509version (and API Level) and fully test your application. Make sure to declare a 510<code>android:minSdkVersion</code> attribute in the application's manifest and 511set its value to the API Level of the platform version. </p> 512 513<h3 id="apilevel">Declaring a minimum API Level</h3> 514 515<p>If you build an application that uses APIs or system features introduced in 516the latest platform version, you should set the 517<code>android:minSdkVersion</code> attribute to the API Level of the latest 518platform version. This ensures that users will only be able to install your 519application if their devices are running a compatible version of the Android 520platform. In turn, this ensures that your application can function properly on 521their devices. </p> 522 523<p>If your application uses APIs introduced in the latest platform version but 524does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then 525it will run properly on devices running the latest version of the platform, but 526<em>not</em> on devices running earlier versions of the platform. In the latter 527case, the application will crash at runtime when it tries to use APIs that don't 528exist on the earlier versions.</p> 529 530<h3 id="testing">Testing against higher API Levels</h3> 531 532<p>After compiling your application, you should make sure to test it on the 533platform specified in the application's <code>android:minSdkVersion</code> 534attribute. To do so, create an AVD that uses the platform version required by 535your application. Additionally, to ensure forward-compatibility, you should run 536and test the application on all platforms that use a higher API Level than that 537used by your application. </p> 538 539<p>The Android SDK includes multiple platform versions that you can use, 540including the latest version, and provides an updater tool that you can use to 541download other platform versions as necessary. </p> 542 543<p>To access the updater, use the <code>android</code> command-line tool, 544located in the <sdk>/tools directory. You can launch the SDK updater by 545executing <code>android sdk</code>. You can 546also simply double-click the android.bat (Windows) or android (OS X/Linux) file. 547In ADT, you can also access the updater by selecting 548<strong>Window</strong> > <strong>Android SDK 549Manager</strong>.</p> 550 551<p>To run your application against different platform versions in the emulator, 552create an AVD for each platform version that you want to test. For more 553information about AVDs, see <a 554href="{@docRoot}tools/devices/index.html">Creating and Managing Virtual Devices</a>. If 555you are using a physical device for testing, ensure that you know the API Level 556of the Android platform it runs. See the table at the top of this document for 557a list of platform versions and their API Levels. </p> 558 559 560<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> 561 562<p>Reference documentation pages on the Android Developers site offer a "Filter 563by API Level" control in the top-right area of each page. You can use the 564control to show documentation only for parts of the API that are actually 565accessible to your application, based on the API Level that it specifies in 566the <code>android:minSdkVersion</code> attribute of its manifest file. </p> 567 568<p>To use filtering, select the checkbox to enable filtering, just below the 569page search box. Then set the "Filter by API Level" control to the same API 570Level as specified by your application. Notice that APIs introduced in a later 571API Level are then grayed out and their content is masked, since they would not 572be accessible to your application. </p> 573 574<p>Filtering by API Level in the documentation does not provide a view 575of what is new or introduced in each API Level — it simply provides a way 576to view the entire API associated with a given API Level, while excluding API 577elements introduced in later API Levels.</p> 578 579<p>If you decide that you don't want to filter the API documentation, just 580disable the feature using the checkbox. By default, API Level filtering is 581disabled, so that you can view the full framework API, regardless of API Level. 582</p> 583 584<p>Also note that the reference documentation for individual API elements 585specifies the API Level at which each element was introduced. The API Level 586for packages and classes is specified as "Since <api level>" at the 587top-right corner of the content area on each documentation page. The API Level 588for class members is specified in their detailed description headers, 589at the right margin. </p> 590 591 592 593 594 595 596 597 598 599