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