1 page.title=Android API Levels 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#intro">What is API Level?</a></li> 10 <li><a href="#uses">Uses of API Level in Android</a></li> 11 <li><a href="#considerations">Development Considerations</a> 12 <ol> 13 <li><a href="#fc">Application forward compatibility</a></li> 14 <li><a href="#bc">Application backward compatibility</a></li> 15 <li><a href="#platform">Selecting a platform version and API Level</a></li> 16 <li><a href="#apilevel">Declaring a minimum API Level</a></li> 17 <li><a href="#testing">Testing against higher API Levels</a></li> 18 </ol> 19 </li> 20 <li><a href="#provisional">Using a Provisional API Level</a></li> 21 <li><a href="#filtering">Filtering the Documentation</a></li> 22 </ol> 23 24 <h2>See also</h2> 25 <ol> 26 <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li> 27 </ol> 28 29 </div> 30 </div> 31 32 <p>As you develop your application on Android, it's useful to understand the 33 platform's general approach to API change management. It's also important to 34 understand the API Level identifier and the role it plays in ensuring your 35 application's compatibility with devices on which it may be installed. </p> 36 37 <p>The sections below provide information about API Level and how it affects 38 your applications. </p> 39 40 <p>For information about how to use the "Filter by API Level" control 41 available in the API reference documentation, see 42 <a href="#filtering">Filtering the documentation</a> at the 43 end of this document. </p> 44 45 <h2 id="intro">What is API Level?</h2> 46 47 <p>API Level is an integer value that uniquely identifies the framework API 48 revision offered by a version of the Android platform.</p> 49 50 <p>The Android platform provides a framework API that applications can use to 51 interact with the underlying Android system. The framework API consists of:</p> 52 53 <ul> 54 <li>A core set of packages and classes</li> 55 <li>A set of XML elements and attributes for declaring a manifest file</li> 56 <li>A set of XML elements and attributes for declaring and accessing resources</li> 57 <li>A set of Intents</li> 58 <li>A set of permissions that applications can request, as well as permission 59 enforcements included in the system</li> 60 </ul> 61 62 <p>Each successive version of the Android platform can include updates to the 63 Android application framework API that it delivers. </p> 64 65 <p>Updates to the framework API are designed so that the new API remains 66 compatible with earlier versions of the API. That is, most changes in the API 67 are additive and introduce new or replacement functionality. As parts of the API 68 are upgraded, the older replaced parts are deprecated but are not removed, so 69 that existing applications can still use them. In a very small number of cases, 70 parts of the API may be modified or removed, although typically such changes are 71 only needed to ensure API robustness and application or system security. All 72 other API parts from earlier revisions are carried forward without 73 modification.</p> 74 75 <p>The framework API that an Android platform delivers is specified using an 76 integer identifier called "API Level". Each Android platform version supports 77 exactly one API Level, although support is implicit for all earlier API Levels 78 (down to API Level 1). The initial release of the Android platform provided 79 API Level 1 and subsequent releases have incremented the API Level.</p> 80 81 <p>The following table specifies the API Level supported by each version of the 82 Android platform.</p> 83 84 <table> 85 <tr><th>Platform Version</th><th>API Level</th><th>VERSION_CODE</th><th>Notes</th></tr> 86 87 <tr><td><a href="{@docRoot}about/versions/android-4.0.3.html">Android 4.0.3</a></td> 88 <td><a href="{@docRoot}sdk/api_diff/15/changes.html" title="Diff Report">15</a></td> 89 <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1}</td> 90 <td rowspan="2"><a href="{@docRoot}about/versions/android-4.0-highlights.html">Platform 91 Highlights</a></td></tr> 92 93 <tr><td><a href="{@docRoot}about/versions/android-4.0.html">Android 4.0, 4.0.1, 4.0.2</a></td> 94 <td><a href="{@docRoot}sdk/api_diff/14/changes.html" title="Diff Report">14</a></td> 95 <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}</td> 96 </tr> 97 98 <tr><td><a href="{@docRoot}about/versions/android-3.2.html">Android 3.2</a></td> 99 <td><a href="{@docRoot}sdk/api_diff/13/changes.html" title="Diff Report">13</a></td> 100 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}</td> 101 <td><!-- <a href="{@docRoot}about/versions/android-3.2-highlights.html">Platform Highlights</a>--></td></tr> 102 103 <tr><td><a href="{@docRoot}about/versions/android-3.1.html">Android 3.1.x</a></td> 104 <td><a href="{@docRoot}sdk/api_diff/12/changes.html" title="Diff Report">12</a></td> 105 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR1}</td> 106 <td><a href="{@docRoot}about/versions/android-3.1-highlights.html">Platform Highlights</a></td></tr> 107 108 <tr><td><a href="{@docRoot}about/versions/android-3.0.html">Android 3.0.x</td> 109 <td><a href="{@docRoot}sdk/api_diff/11/changes.html" title="Diff Report">11</a></td> 110 <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB}</td> 111 <td><a href="{@docRoot}about/versions/android-3.0-highlights.html">Platform Highlights</a></td></tr> 112 113 <tr><td><a href="{@docRoot}about/versions/android-2.3.3.html">Android 2.3.4<br>Android 2.3.3</td> 114 <td><a href="{@docRoot}sdk/api_diff/10/changes.html" title="Diff Report">10</a></td> 115 <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD_MR1}</td> 116 <td rowspan="2"><a href="{@docRoot}about/versions/android-2.3-highlights.html">Platform Highlights</a></td></tr> 117 118 <tr><td><a href="{@docRoot}about/versions/android-2.3.html">Android 2.3.2<br>Android 2.3.1<br>Android 2.3</td> 119 <td><a href="{@docRoot}sdk/api_diff/9/changes.html" title="Diff Report">9</a></td> 120 <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD}</td> 121 </tr> 122 123 <tr><td><a href="{@docRoot}about/versions/android-2.2.html">Android 2.2.x</td> 124 <td ><a href="{@docRoot}sdk/api_diff/8/changes.html" title="Diff Report">8</a></td> 125 <td>{@link android.os.Build.VERSION_CODES#FROYO}</td> 126 <td><a href="{@docRoot}about/versions/android-2.2-highlights.html">Platform Highlights</a></td></tr> 127 128 <tr><td><a href="{@docRoot}about/versions/android-2.1.html">Android 2.1.x</td> 129 <td><a href="{@docRoot}sdk/api_diff/7/changes.html" title="Diff Report">7</a></td> 130 <td>{@link android.os.Build.VERSION_CODES#ECLAIR_MR1}</td> 131 <td rowspan="3" ><a href="{@docRoot}about/versions/android-2.0-highlights.html">Platform Highlights</a></td></tr> 132 133 <tr><td><a href="{@docRoot}about/versions/android-2.0.1.html">Android 2.0.1</td> 134 <td><a href="{@docRoot}sdk/api_diff/6/changes.html" title="Diff Report">6</a></td> 135 <td>{@link android.os.Build.VERSION_CODES#ECLAIR_0_1}</td> 136 </tr> 137 138 <tr><td><a href="{@docRoot}about/versions/android-2.0.html">Android 2.0</td> 139 <td><a href="{@docRoot}sdk/api_diff/5/changes.html" title="Diff Report">5</a></td> 140 <td>{@link android.os.Build.VERSION_CODES#ECLAIR}</td> 141 </tr> 142 143 <tr><td><a href="{@docRoot}about/versions/android-1.6.html">Android 1.6</td> 144 <td><a href="{@docRoot}sdk/api_diff/4/changes.html" title="Diff Report">4</a></td> 145 <td>{@link android.os.Build.VERSION_CODES#DONUT}</td> 146 <td><a href="{@docRoot}about/versions/android-1.6-highlights.html">Platform Highlights</a></td></tr> 147 148 <tr><td><a href="{@docRoot}about/versions/android-1.5.html">Android 1.5</td> 149 <td><a href="{@docRoot}sdk/api_diff/3/changes.html" title="Diff Report">3</a></td> 150 <td>{@link android.os.Build.VERSION_CODES#CUPCAKE}</td> 151 <td><a href="{@docRoot}about/versions/android-1.5-highlights.html">Platform Highlights</a></td></tr> 152 153 <tr><td><a href="{@docRoot}about/versions/android-1.1.html">Android 1.1</td> 154 <td>2</td> 155 <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> 156 157 <tr><td>Android 1.0</td> 158 <td>1</td> 159 <td>{@link android.os.Build.VERSION_CODES#BASE}</td> 160 <td></td></tr> 161 </table> 162 163 164 <h2 id="uses">Uses of API Level in Android</h2> 165 166 <p>The API Level identifier serves a key role in ensuring the best possible 167 experience for users and application developers: 168 169 <ul> 170 <li>It lets the Android platform describe the maximum framework API revision 171 that it supports</li> 172 <li>It lets applications describe the framework API revision that they 173 require</li> 174 <li>It lets the system negotiate the installation of applications on the user's 175 device, such that version-incompatible applications are not installed.</li> 176 </ul> 177 178 <p>Each Android platform version stores its API Level identifier internally, in 179 the Android system itself. </p> 180 181 <p>Applications can use a manifest element provided by the framework API — 182 <code><uses-sdk></code> — to describe the minimum and maximum API 183 Levels under which they are able to run, as well as the preferred API Level that 184 they are designed to support. The element offers three key attributes:</p> 185 186 <ul> 187 <li><code>android:minSdkVersion</code> — Specifies the minimum API Level 188 on which the application is able to run. The default value is "1".</li> 189 <li><code>android:targetSdkVersion</code> — Specifies the API Level 190 on which the application is designed to run. In some cases, this allows the 191 application to use manifest elements or behaviors defined in the target 192 API Level, rather than being restricted to using only those defined 193 for the minimum API Level.</li> 194 <li><code>android:maxSdkVersion</code> — Specifies the maximum API Level 195 on which the application is able to run. <strong>Important:</strong> Please read the <a 196 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 197 documentation before using this attribute. </li> 198 </ul> 199 200 <p>For example, to specify the minimum system API Level that an application 201 requires in order to run, the application would include in its manifest a 202 <code><uses-sdk></code> element with a <code>android:minSdkVersion</code> 203 attribute. The value of <code>android:minSdkVersion</code> would be the integer 204 corresponding to the API Level of the earliest version of the Android platform 205 under which the application can run. </p> 206 207 <p>When the user attempts to install an application, or when revalidating an 208 appplication after a system update, the Android system first checks the 209 <code><uses-sdk></code> attributes in the application's manifest and 210 compares the values against its own internal API Level. The system allows the 211 installation to begin only if these conditions are met:</p> 212 213 <ul> 214 <li>If a <code>android:minSdkVersion</code> attribute is declared, its value 215 must be less than or equal to the system's API Level integer. If not declared, 216 the system assumes that the application requires API Level 1. </li> 217 <li>If a <code>android:maxSdkVersion</code> attribute is declared, its value 218 must be equal to or greater than the system's API Level integer. 219 If not declared, the system assumes that the application 220 has no maximum API Level. Please read the <a 221 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 222 documentation for more information about how the system handles this attribute.</li> 223 </ul> 224 225 <p>When declared in an application's manifest, a <code><uses-sdk></code> 226 element might look like this: </p> 227 228 <pre><manifest> 229 <uses-sdk android:minSdkVersion="5" /> 230 ... 231 </manifest></pre> 232 233 <p>The principal reason that an application would declare an API Level in 234 <code>android:minSdkVersion</code> is to tell the Android system that it is 235 using APIs that were <em>introduced</em> in the API Level specified. If the 236 application were to be somehow installed on a platform with a lower API Level, 237 then it would crash at run-time when it tried to access APIs that don't exist. 238 The system prevents such an outcome by not allowing the application to be 239 installed if the lowest API Level it requires is higher than that of the 240 platform version on the target device.</p> 241 242 <p>For example, the {@link android.appwidget} package was introduced with API 243 Level 3. If an application uses that API, it must declare a 244 <code>android:minSdkVersion</code> attribute with a value of "3". The 245 application will then be installable on platforms such as Android 1.5 (API Level 246 3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and 247 Android 1.0 platforms (API Level 1).</p> 248 249 <p>For more information about how to specify an application's API Level 250 requirements, see the <a 251 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 252 section of the manifest file documentation.</p> 253 254 255 <h2 id="considerations">Development Considerations</h2> 256 257 <p>The sections below provide information related to API level that you should 258 consider when developing your application.</p> 259 260 <h3 id="fc">Application forward compatibility</h3> 261 262 <p>Android applications are generally forward-compatible with new versions of 263 the Android platform.</p> 264 265 <p>Because almost all changes to the framework API are additive, an Android 266 application developed using any given version of the API (as specified by its 267 API Level) is forward-compatible with later versions of the Android platform and 268 higher API levels. The application should be able to run on all later versions 269 of the Android platform, except in isolated cases where the application uses a 270 part of the API that is later removed for some reason. </p> 271 272 <p>Forward compatibility is important because many Android-powered devices 273 receive over-the-air (OTA) system updates. The user may install your 274 application and use it successfully, then later receive an OTA update to a new 275 version of the Android platform. Once the update is installed, your application 276 will run in a new run-time version of the environment, but one that has the API 277 and system capabilities that your application depends on. </p> 278 279 <p>In some cases, changes <em>below</em> the API, such those in the underlying 280 system itself, may affect your application when it is run in the new 281 environment. For that reason it's important for you, as the application 282 developer, to understand how the application will look and behave in each system 283 environment. To help you test your application on various versions of the Android 284 platform, the Android SDK includes multiple platforms that you can download. 285 Each platform includes a compatible system image that you can run in an AVD, to 286 test your application. </p> 287 288 <h3 id="bc">Application backward compatibility</h3> 289 290 <p>Android applications are not necessarily backward compatible with versions of 291 the Android platform older than the version against which they were compiled. 292 </p> 293 294 <p>Each new version of the Android platform can include new framework APIs, such 295 as those that give applications access to new platform capabilities or replace 296 existing API parts. The new APIs are accessible to applications when running on 297 the new platform and, as mentioned above, also when running on later versions of 298 the platform, as specified by API Level. Conversely, because earlier versions of 299 the platform do not include the new APIs, applications that use the new APIs are 300 unable to run on those platforms.</p> 301 302 <p>Although it's unlikely that an Android-powered device would be downgraded to 303 a previous version of the platform, it's important to realize that there are 304 likely to be many devices in the field that run earlier versions of the 305 platform. Even among devices that receive OTA updates, some might lag and 306 might not receive an update for a significant amount of time. </p> 307 308 <h3 id="platform">Selecting a platform version and API Level</h3> 309 310 <p>When you are developing your application, you will need to choose 311 the platform version against which you will compile the application. In 312 general, you should compile your application against the lowest possible 313 version of the platform that your application can support. 314 315 <p>You can determine the lowest possible platform version by compiling the 316 application against successively lower build targets. After you determine the 317 lowest version, you should create an AVD using the corresponding platform 318 version (and API Level) and fully test your application. Make sure to declare a 319 <code>android:minSdkVersion</code> attribute in the application's manifest and 320 set its value to the API Level of the platform version. </p> 321 322 <h3 id="apilevel">Declaring a minimum API Level</h3> 323 324 <p>If you build an application that uses APIs or system features introduced in 325 the latest platform version, you should set the 326 <code>android:minSdkVersion</code> attribute to the API Level of the latest 327 platform version. This ensures that users will only be able to install your 328 application if their devices are running a compatible version of the Android 329 platform. In turn, this ensures that your application can function properly on 330 their devices. </p> 331 332 <p>If your application uses APIs introduced in the latest platform version but 333 does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then 334 it will run properly on devices running the latest version of the platform, but 335 <em>not</em> on devices running earlier versions of the platform. In the latter 336 case, the application will crash at runtime when it tries to use APIs that don't 337 exist on the earlier versions.</p> 338 339 <h3 id="testing">Testing against higher API Levels</h3> 340 341 <p>After compiling your application, you should make sure to test it on the 342 platform specified in the application's <code>android:minSdkVersion</code> 343 attribute. To do so, create an AVD that uses the platform version required by 344 your application. Additionally, to ensure forward-compatibility, you should run 345 and test the application on all platforms that use a higher API Level than that 346 used by your application. </p> 347 348 <p>The Android SDK includes multiple platform versions that you can use, 349 including the latest version, and provides an updater tool that you can use to 350 download other platform versions as necessary. </p> 351 352 <p>To access the updater, use the <code>android</code> command-line tool, 353 located in the <sdk>/tools directory. You can launch the SDK updater by 354 executing <code>android sdk</code>. You can 355 also simply double-click the android.bat (Windows) or android (OS X/Linux) file. 356 In ADT, you can also access the updater by selecting 357 <strong>Window</strong> > <strong>Android SDK 358 Manager</strong>.</p> 359 360 <p>To run your application against different platform versions in the emulator, 361 create an AVD for each platform version that you want to test. For more 362 information about AVDs, see <a 363 href="{@docRoot}tools/devices/index.html">Creating and Managing Virtual Devices</a>. If 364 you are using a physical device for testing, ensure that you know the API Level 365 of the Android platform it runs. See the table at the top of this document for 366 a list of platform versions and their API Levels. </p> 367 368 <h2 id="provisional">Using a Provisional API Level</h2> 369 370 <p>In some cases, an "Early Look" Android SDK platform may be available. To let 371 you begin developing on the platform although the APIs may not be final, the 372 platform's API Level integer will not be specified. You must instead use the 373 platform's <em>provisional API Level</em> in your application manifest, in order 374 to build applications against the platform. A provisional API Level is not an 375 integer, but a string matching the codename of the unreleased platform version. 376 The provisional API Level will be specified in the release notes for the Early 377 Look SDK release notes and is case-sensitive.</p> 378 379 <p>The use of a provisional API Level is designed to protect developers and 380 device users from inadvertently publishing or installing applications based on 381 the Early Look framework API, which may not run properly on actual devices 382 running the final system image.</p> 383 384 <p>The provisional API Level will only be valid while using the Early Look SDK 385 and can only be used to run applications in the emulator. An application using 386 the provisional API Level can never be installed on an Android device. At the 387 final release of the platform, you must replace any instances of the provisional 388 API Level in your application manifest with the final platform's actual API 389 Level integer.</p> 390 391 392 <h2 id="filtering">Filtering the Reference Documentation by API Level</h2> 393 394 <p>Reference documentation pages on the Android Developers site offer a "Filter 395 by API Level" control in the top-right area of each page. You can use the 396 control to show documentation only for parts of the API that are actually 397 accessible to your application, based on the API Level that it specifies in 398 the <code>android:minSdkVersion</code> attribute of its manifest file. </p> 399 400 <p>To use filtering, select the checkbox to enable filtering, just below the 401 page search box. Then set the "Filter by API Level" control to the same API 402 Level as specified by your application. Notice that APIs introduced in a later 403 API Level are then grayed out and their content is masked, since they would not 404 be accessible to your application. </p> 405 406 <p>Filtering by API Level in the documentation does not provide a view 407 of what is new or introduced in each API Level — it simply provides a way 408 to view the entire API associated with a given API Level, while excluding API 409 elements introduced in later API Levels.</p> 410 411 <p>If you decide that you don't want to filter the API documentation, just 412 disable the feature using the checkbox. By default, API Level filtering is 413 disabled, so that you can view the full framework API, regardless of API Level. 414 </p> 415 416 <p>Also note that the reference documentation for individual API elements 417 specifies the API Level at which each element was introduced. The API Level 418 for packages and classes is specified as "Since <api level>" at the 419 top-right corner of the content area on each documentation page. The API Level 420 for class members is specified in their detailed description headers, 421 at the right margin. </p> 422
