| page.title=Android API Levels |
| @jd:body |
| |
| |
| <p>The Android <em>API Level</em> is an integer that indicates a set of APIs available in an Android SDK |
| and on a version of the Android platform. Each version of the Android platform supports a specific set |
| of APIs, which are always backward-compatible. For example, Android 1.5 supports all APIs available in |
| Android 1.0, but the reverse is not true. If an application uses APIs |
| available in Android 1.5 that are not available in 1.0, then the application should never be installed |
| on an Android 1.0 device, because it will fail due to missing APIs. The API Level ensures this does not happen |
| by comparing the minimum API Level required by the applicaiton to the API Level available on the device.</p> |
| |
| <p>When a new version of Android adds APIs, a new API Level is added to the platform. The new APIs |
| are available only to applications that declare a minimum API Level that is equal-to or greater-than |
| the API Level in which the APIs were introduced. The API Level required by an application is declared with the |
| <code><uses-sdk></code> element inside the Android manifest, like this:</p> |
| |
| <pre><uses-sdk android:minSdkVersion="3" /></pre> |
| |
| <p>The value for <code>minSdkVersion</code> is the minimum API Level required by the application. |
| If this is not declared, then it is assumed that the application is compatible with all versions and defaults to |
| API Level 1. In which case, if the application actually uses APIs introduced with an API Level greater than 1, then |
| the application will fail in unpredictable ways when installed on a device that only supports API Level 1 |
| (such as an Android 1.0 device). |
| See the <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> |
| documentation for more about declaring the API Level in your manifest.</p> |
| |
| <p>For example, the {@link android.appwidget} package was introduced with API Level 3. If your application |
| has set <code>minSdkVersion</code> to 1 or 2, then your application cannot use this package, |
| even if the device running your application uses a version of Android that supports it. |
| In order to use the {@link android.appwidget} package, your application must set <code>minSdkVersion</code> |
| to 3 or higher. When the <code>minSdkVersion</code> is set to 3, the application will no longer be able to install |
| on a device running a platform version with an API Level less than 3.</p> |
| |
| <p>Despite the name of the manifest attribute (<code>minSdkVersion</code>), the API Level is not directly |
| associated with a specific SDK. For example, the SDK for Android 1.0 uses |
| API Level 1 and the SDK for Android 1.1 uses API Level 2. So it may seem that the API Level increases consistently. |
| However, it's possible that a subsequent platform |
| releases will not introduce new APIs, and thus, the API Level will remain the same. In addition, there are often |
| multiple SDK releases for a single platform version (there were three SDK releases for Android 1.5), and |
| there's no guarantee that the API Level will remain the same between these. It's possible (but unlikely) that |
| a second or third SDK for a given version of the platform will provide new APIs and add a new API Level. |
| When you install a new SDK, be sure to read the SDK Contents on the install page, which specifies the API |
| Level for each platform available in the SDK. Also see the comparison of |
| <a href="#VersionsVsApiLevels">Platform Versions vs. API Levels</a>, below.</p> |
| |
| <p class="note"><strong>Note:</strong> During an "Early Look" SDK release, the APIs may not be final, so the |
| API Level number cannot be specified. In this case, a string value matching the |
| platform codename must be used as the value for <code>minSdkVersion</code>. This codename value |
| will only be valid while using the Early Look SDK with the emulator. An application using this API Level |
| can never be installed on an Android device. When the final SDK is released, you must update your manifest to use |
| the official API Level integer.</p> |
| |
| <h2 id="VersionsVsApiLevels">Platform Versions vs. API Levels</h2> |
| |
| <p>The following table specifies the <em>maximum</em> API Level supported by each version of the Android platform. |
| (Every platform is backward-compatible to API Level 1.)</p> |
| |
| <table> |
| <tr><th>Platform Version</th><th>API Level</th></tr> |
| <tr><td>Android 1.0</td><td>1</td></tr> |
| <tr><td>Android 1.1</td><td>2</td></tr> |
| <tr><td>Android 1.5</td><td>3</td></tr> |
| <tr><td>Android Donut</td><td>Donut</td></tr> |
| </table> |
| |
| |
| <h2 id="ViewingTheApiReference">Viewing the API Reference Based on API Level</h2> |
| |
| <p>The Android API reference includes information that specififies the minimum API Level required for each |
| package, class, and member. You can see this information on the right side of each header or label.</p> |
| |
| <p>By default, the reference documentation shows all APIs available with the latest SDK release. |
| This means that the reference assumes you're using the latest API Level and will show you everything available |
| with it. If you're developing applications for a version of Android that does not support the latest API Level, |
| then you can filter the reference to reveal only the packages, classes, and members available for that API Level. |
| When viewing the reference, use the "Filter by API Level" selection box (below the search box) to pick the API Level |
| you'd like to view.</p> |
| |
| |
| |