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></tr> 86 <tr><td>Android 2.2</td><td>8</td></tr> 87 <tr><td>Android 2.1</td><td>7</td></tr> 88 <tr><td>Android 2.0.1</td><td>6</td></tr> 89 <tr><td>Android 2.0</td><td>5</td></tr> 90 <tr><td>Android 1.6</td><td>4</td></tr> 91 <tr><td>Android 1.5</td><td>3</td></tr> 92 <tr><td>Android 1.1</td><td>2</td></tr> 93 <tr><td>Android 1.0</td><td>1</td></tr> 94 </table> 95 96 97 <h2 id="uses">Uses of API Level in Android</h2> 98 99 <p>The API Level identifier serves a key role in ensuring the best possible 100 experience for users and application developers: 101 102 <ul> 103 <li>It lets the Android platform describe the maximum framework API revision 104 that it supports</li> 105 <li>It lets applications describe the framework API revision that they 106 require</li> 107 <li>It lets the system negotiate the installation of applications on the user's 108 device, such that version-incompatible applications are not installed.</li> 109 </ul> 110 111 <p>Each Android platform version stores its API Level identifier internally, in 112 the Android system itself. </p> 113 114 <p>Applications can use a manifest element provided by the framework API — 115 <code><uses-sdk></code> — to describe the minimum and maximum API 116 Levels under which they are able to run, as well as the preferred API Level that 117 they are designed to support. The element offers three key attributes:</p> 118 119 <ul> 120 <li><code>android:minSdkVersion</code> — Specifies the minimum API Level 121 on which the application is able to run. The default value is "1".</li> 122 <li><code>android:targetSdkVersion</code> — Specifies the API Level 123 on which the application is designed to run. In some cases, this allows the 124 application to use manifest elements or behaviors defined in the target 125 API Level, rather than being restricted to using only those defined 126 for the minimum API Level.</li> 127 <li><code>android:maxSdkVersion</code> — Specifies the maximum API Level 128 on which the application is able to run. <strong>Important:</strong> Please read the <a 129 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 130 documentation before using this attribute. </li> 131 </ul> 132 133 <p>For example, to specify the minimum system API Level that an application 134 requires in order to run, the application would include in its manifest a 135 <code><uses-sdk></code> element with a <code>android:minSdkVersion</code> 136 attribute. The value of <code>android:minSdkVersion</code> would be the integer 137 corresponding to the API Level of the earliest version of the Android platform 138 under which the application can run. </p> 139 140 <p>When the user attempts to install an application, or when revalidating an 141 appplication after a system update, the Android system first checks the 142 <code><uses-sdk></code> attributes in the application's manifest and 143 compares the values against its own internal API Level. The system allows the 144 installation to begin only if these conditions are met:</p> 145 146 <ul> 147 <li>If a <code>android:minSdkVersion</code> attribute is declared, its value 148 must be less than or equal to the system's API Level integer. If not declared, 149 the system assumes that the application requires API Level 1. </li> 150 <li>If a <code>android:maxSdkVersion</code> attribute is declared, its value 151 must be equal to or greater than the system's API Level integer. 152 If not declared, the system assumes that the application 153 has no maximum API Level. Please read the <a 154 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 155 documentation for more information about how the system handles this attribute.</li> 156 </ul> 157 158 <p>When declared in an application's manifest, a <code><uses-sdk></code> 159 element might look like this: </p> 160 161 <pre><manifest> 162 ... 163 <uses-sdk android:minSdkVersion="5" /> 164 ... 165 </manifest></pre> 166 167 <p>The principal reason that an application would declare an API Level in 168 <code>android:minSdkVersion</code> is to tell the Android system that it is 169 using APIs that were <em>introduced</em> in the API Level specified. If the 170 application were to be somehow installed on a platform with a lower API Level, 171 then it would crash at run-time when it tried to access APIs that don't exist. 172 The system prevents such an outcome by not allowing the application to be 173 installed if the lowest API Level it requires is higher than that of the 174 platform version on the target device.</p> 175 176 <p>For example, the {@link android.appwidget} package was introduced with API 177 Level 3. If an application uses that API, it must declare a 178 <code>android:minSdkVersion</code> attribute with a value of "3". The 179 application will then be installable on platforms such as Android 1.5 (API Level 180 3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and 181 Android 1.0 platforms (API Level 1).</p> 182 183 <p>For more information about how to specify an application's API Level 184 requirements, see the <a 185 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 186 section of the manifest file documentation.</p> 187 188 189 <h2 id="considerations">Development Considerations</h2> 190 191 <p>The sections below provide information related to API level that you should 192 consider when developing your application.</p> 193 194 <h3 id="fc">Application forward compatibility</h3> 195 196 <p>Android applications are generally forward-compatible with new versions of 197 the Android platform.</p> 198 199 <p>Because almost all changes to the framework API are additive, an Android 200 application developed using any given version of the API (as specified by its 201 API Level) is forward-compatible with later versions of the Android platform and 202 higher API levels. The application should be able to run on all later versions 203 of the Android platform, except in isolated cases where the application uses a 204 part of the API that is later removed for some reason. </p> 205 206 <p>Forward compatibility is important because many Android-powered devices 207 receive over-the-air (OTA) system updates. The user may install your 208 application and use it successfully, then later receive an OTA update to a new 209 version of the Android platform. Once the update is installed, your application 210 will run in a new run-time version of the environment, but one that has the API 211 and system capabilities that your application depends on. </p> 212 213 <p>In some cases, changes <em>below</em> the API, such those in the underlying 214 system itself, may affect your application when it is run in the new 215 environment. For that reason it's important for you, as the application 216 developer, to understand how the application will look and behave in each system 217 environment. To help you test your application on various versions of the Android 218 platform, the Android SDK includes multiple platforms that you can download. 219 Each platform includes a compatible system image that you can run in an AVD, to 220 test your application. </p> 221 222 <h3 id="bc">Application backward compatibility</h3> 223 224 <p>Android applications are not necessarily backward compatible with versions of 225 the Android platform older than the version against which they were compiled. 226 </p> 227 228 <p>Each new version of the Android platform can include new framework APIs, such 229 as those that give applications access to new platform capabilities or replace 230 existing API parts. The new APIs are accessible to applications when running on 231 the new platform and, as mentioned above, also when running on later versions of 232 the platform, as specified by API Level. Conversely, because earlier versions of 233 the platform do not include the new APIs, applications that use the new APIs are 234 unable to run on those platforms.</p> 235 236 <p>Although it's unlikely that an Android-powered device would be downgraded to 237 a previous version of the platform, it's important to realize that there are 238 likely to be many devices in the field that run earlier versions of the 239 platform. Even among devices that receive OTA updates, some might lag and 240 might not receive an update for a significant amount of time. </p> 241 242 <h3 id="platform">Selecting a platform version and API Level</h3> 243 244 <p>When you are developing your application, you will need to choose 245 the platform version against which you will compile the application. In 246 general, you should compile your application against the lowest possible 247 version of the platform that your application can support. 248 249 <p>You can determine the lowest possible platform version by compiling the 250 application against successively lower build targets. After you determine the 251 lowest version, you should create an AVD using the corresponding platform 252 version (and API Level) and fully test your application. Make sure to declare a 253 <code>android:minSdkVersion</code> attribute in the application's manifest and 254 set its value to the API Level of the platform version. </p> 255 256 <h3 id="apilevel">Declaring a minimum API Level</h3> 257 258 <p>If you build an application that uses APIs or system features introduced in 259 the latest platform version, you should set the 260 <code>android:minSdkVersion</code> attribute to the API Level of the latest 261 platform version. This ensures that users will only be able to install your 262 application if their devices are running a compatible version of the Android 263 platform. In turn, this ensures that your application can function properly on 264 their devices. </p> 265 266 <p>If your application uses APIs introduced in the latest platform version but 267 does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then 268 it will run properly on devices running the latest version of the platform, but 269 <em>not</em> on devices running earlier versions of the platform. In the latter 270 case, the application will crash at runtime when it tries to use APIs that don't 271 exist on the earlier versions.</p> 272 273 <h3 id="testing">Testing against higher API Levels</h3> 274 275 <p>After compiling your application, you should make sure to test it on the 276 platform specified in the application's <code>android:minSdkVersion</code> 277 attribute. To do so, create an AVD that uses the platform version required by 278 your application. Additionally, to ensure forward-compatibility, you should run 279 and test the application on all platforms that use a higher API Level than that 280 used by your application. </p> 281 282 <p>The Android SDK includes multiple platform versions that you can use, 283 including the latest version, and provides an updater tool that you can use to 284 download other platform versions as necessary. </p> 285 286 <p>To access the updater, use the <code>android</code> command-line tool, 287 located in the <sdk>/tools directory. You can launch the Updater by using 288 the <code>android</code> command without specifying any options. You can 289 also simply double-click the android.bat (Windows) or android (OS X/Linux) file. 290 In ADT, you can also access the updater by selecting 291 <strong>Window</strong> > <strong>Android SDK and AVD 292 Manager</strong>.</p> 293 294 <p>To run your application against different platform versions in the emulator, 295 create an AVD for each platform version that you want to test. For more 296 information about AVDs, see <a 297 href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. If 298 you are using a physical device for testing, ensure that you know the API Level 299 of the Android platform it runs. See the table at the top of this document for 300 a list of platform versions and their API Levels. </p> 301 302 303 <h2 id="provisional">Using a Provisional API Level</h2> 304 305 <p>In some cases, an "Early Look" Android SDK platform may be available. To let 306 you begin developing on the platform although the APIs may not be final, the 307 platform's API Level integer will not be specified. You must instead use the 308 platform's <em>provisional API Level</em> in your application manifest, in order 309 to build applications against the platform. A provisional API Level is not an 310 integer, but a string matching the codename of the unreleased platform version. 311 The provisional API Level will be specified in the release notes for the Early 312 Look SDK release notes and is case-sensitive.</p> 313 314 <p>The use of a provisional API Level is designed to protect developers and 315 device users from inadvertently publishing or installing applications based on 316 the Early Look framework API, which may not run properly on actual devices 317 running the final system image.</p> 318 319 <p>The provisional API Level will only be valid while using the Early Look SDK 320 and can only be used to run applications in the emulator. An application using 321 the provisional API Level can never be installed on an Android device. At the 322 final release of the platform, you must replace any instances of the provisional 323 API Level in your application manifest with the final platform's actual API 324 Level integer.</p> 325 326 327 <h2 id="filtering">Filtering the Reference Documentation by API Level</h2> 328 329 <p>Reference documentation pages on the Android Developers site offer a "Filter 330 by API Level" control in the top-right area of each page. You can use the 331 control to show documentation only for parts of the API that are actually 332 accessible to your application, based on the API Level that it specifies in 333 the <code>android:minSdkVersion</code> attribute of its manifest file. </p> 334 335 <p>To use filtering, select the checkbox to enable filtering, just below the 336 page search box. Then set the "Filter by API Level" control to the same API 337 Level as specified by your application. Notice that APIs introduced in a later 338 API Level are then grayed out and their content is masked, since they would not 339 be accessible to your application. </p> 340 341 <p>Filtering by API Level in the documentation does not provide a view 342 of what is new or introduced in each API Level — it simply provides a way 343 to view the entire API associated with a given API Level, while excluding API 344 elements introduced in later API Levels.</p> 345 346 <p>If you decide that you don't want to filter the API documentation, just 347 disable the feature using the checkbox. By default, API Level filtering is 348 disabled, so that you can view the full framework API, regardless of API Level. 349 </p> 350 351 <p>Also note that the reference documentation for individual API elements 352 specifies the API Level at which each element was introduced. The API Level 353 for packages and classes is specified as "Since <api level>" at the 354 top-right corner of the content area on each documentation page. The API Level 355 for class members is specified in their detailed description headers, 356 at the right margin. </p> 357
