358 lines
18 KiB
Plaintext
358 lines
18 KiB
Plaintext
page.title=Android API Levels
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
|
|
<h2>In this document</h2>
|
|
<ol>
|
|
<li><a href="#intro">What is API Level?</a></li>
|
|
<li><a href="#uses">Uses of API Level in Android</a></li>
|
|
<li><a href="#considerations">Development Considerations</a>
|
|
<ol>
|
|
<li><a href="#fc">Application forward compatibility</a></li>
|
|
<li><a href="#bc">Application backward compatibility</a></li>
|
|
<li><a href="#platform">Selecting a platform version and API Level</a></li>
|
|
<li><a href="#apilevel">Declaring a minimum API Level</a></li>
|
|
<li><a href="#testing">Testing against higher API Levels</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#provisional">Using a Provisional API Level</a></li>
|
|
<li><a href="#filtering">Filtering the Documentation</a></li>
|
|
</ol>
|
|
|
|
<h2>See also</h2>
|
|
<ol>
|
|
<li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li>
|
|
</ol>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<p>As you develop your application on Android, it's useful to understand the
|
|
platform's general approach to API change management. It's also important to
|
|
understand the API Level identifier and the role it plays in ensuring your
|
|
application's compatibility with devices on which it may be installed. </p>
|
|
|
|
<p>The sections below provide information about API Level and how it affects
|
|
your applications. </p>
|
|
|
|
<p>For information about how to use the "Filter by API Level" control
|
|
available in the API reference documentation, see
|
|
<a href="#filtering">Filtering the documentation</a> at the
|
|
end of this document. </p>
|
|
|
|
<h2 id="intro">What is API Level?</h2>
|
|
|
|
<p>API Level is an integer value that uniquely identifies the framework API
|
|
revision offered by a version of the Android platform.</p>
|
|
|
|
<p>The Android platform provides a framework API that applications can use to
|
|
interact with the underlying Android system. The framework API consists of:</p>
|
|
|
|
<ul>
|
|
<li>A core set of packages and classes</li>
|
|
<li>A set of XML elements and attributes for declaring a manifest file</li>
|
|
<li>A set of XML elements and attributes for declaring and accessing resources</li>
|
|
<li>A set of Intents</li>
|
|
<li>A set of permissions that applications can request, as well as permission
|
|
enforcements included in the system</li>
|
|
</ul>
|
|
|
|
<p>Each successive version of the Android platform can include updates to the
|
|
Android application framework API that it delivers. </p>
|
|
|
|
<p>Updates to the framework API are designed so that the new API remains
|
|
compatible with earlier versions of the API. That is, most changes in the API
|
|
are additive and introduce new or replacement functionality. As parts of the API
|
|
are upgraded, the older replaced parts are deprecated but are not removed, so
|
|
that existing applications can still use them. In a very small number of cases,
|
|
parts of the API may be modified or removed, although typically such changes are
|
|
only needed to ensure API robustness and application or system security. All
|
|
other API parts from earlier revisions are carried forward without
|
|
modification.</p>
|
|
|
|
<p>The framework API that an Android platform delivers is specified using an
|
|
integer identifier called "API Level". Each Android platform version supports
|
|
exactly one API Level, although support is implicit for all earlier API Levels
|
|
(down to API Level 1). The initial release of the Android platform provided
|
|
API Level 1 and subsequent releases have incremented the API Level.</p>
|
|
|
|
<p>The following table specifies the API Level supported by each version of the
|
|
Android platform.</p>
|
|
|
|
<table>
|
|
<tr><th>Platform Version</th><th>API Level</th></tr>
|
|
<tr><td>Android 2.3.3</td><td>10</td></tr>
|
|
<tr><td>Android 2.3</td><td>9</td></tr>
|
|
<tr><td>Android 2.2</td><td>8</td></tr>
|
|
<tr><td>Android 2.1</td><td>7</td></tr>
|
|
<tr><td>Android 2.0.1</td><td>6</td></tr>
|
|
<tr><td>Android 2.0</td><td>5</td></tr>
|
|
<tr><td>Android 1.6</td><td>4</td></tr>
|
|
<tr><td>Android 1.5</td><td>3</td></tr>
|
|
<tr><td>Android 1.1</td><td>2</td></tr>
|
|
<tr><td>Android 1.0</td><td>1</td></tr>
|
|
</table>
|
|
|
|
|
|
<h2 id="uses">Uses of API Level in Android</h2>
|
|
|
|
<p>The API Level identifier serves a key role in ensuring the best possible
|
|
experience for users and application developers:
|
|
|
|
<ul>
|
|
<li>It lets the Android platform describe the maximum framework API revision
|
|
that it supports</li>
|
|
<li>It lets applications describe the framework API revision that they
|
|
require</li>
|
|
<li>It lets the system negotiate the installation of applications on the user's
|
|
device, such that version-incompatible applications are not installed.</li>
|
|
</ul>
|
|
|
|
<p>Each Android platform version stores its API Level identifier internally, in
|
|
the Android system itself. </p>
|
|
|
|
<p>Applications can use a manifest element provided by the framework API —
|
|
<code><uses-sdk></code> — to describe the minimum and maximum API
|
|
Levels under which they are able to run, as well as the preferred API Level that
|
|
they are designed to support. The element offers three key attributes:</p>
|
|
|
|
<ul>
|
|
<li><code>android:minSdkVersion</code> — Specifies the minimum API Level
|
|
on which the application is able to run. The default value is "1".</li>
|
|
<li><code>android:targetSdkVersion</code> — Specifies the API Level
|
|
on which the application is designed to run. In some cases, this allows the
|
|
application to use manifest elements or behaviors defined in the target
|
|
API Level, rather than being restricted to using only those defined
|
|
for the minimum API Level.</li>
|
|
<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level
|
|
on which the application is able to run. <strong>Important:</strong> Please read the <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
|
|
documentation before using this attribute. </li>
|
|
</ul>
|
|
|
|
<p>For example, to specify the minimum system API Level that an application
|
|
requires in order to run, the application would include in its manifest a
|
|
<code><uses-sdk></code> element with a <code>android:minSdkVersion</code>
|
|
attribute. The value of <code>android:minSdkVersion</code> would be the integer
|
|
corresponding to the API Level of the earliest version of the Android platform
|
|
under which the application can run. </p>
|
|
|
|
<p>When the user attempts to install an application, or when revalidating an
|
|
appplication after a system update, the Android system first checks the
|
|
<code><uses-sdk></code> attributes in the application's manifest and
|
|
compares the values against its own internal API Level. The system allows the
|
|
installation to begin only if these conditions are met:</p>
|
|
|
|
<ul>
|
|
<li>If a <code>android:minSdkVersion</code> attribute is declared, its value
|
|
must be less than or equal to the system's API Level integer. If not declared,
|
|
the system assumes that the application requires API Level 1. </li>
|
|
<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value
|
|
must be equal to or greater than the system's API Level integer.
|
|
If not declared, the system assumes that the application
|
|
has no maximum API Level. Please read the <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
|
|
documentation for more information about how the system handles this attribute.</li>
|
|
</ul>
|
|
|
|
<p>When declared in an application's manifest, a <code><uses-sdk></code>
|
|
element might look like this: </p>
|
|
|
|
<pre><manifest>
|
|
<uses-sdk android:minSdkVersion="5" />
|
|
...
|
|
</manifest></pre>
|
|
|
|
<p>The principal reason that an application would declare an API Level in
|
|
<code>android:minSdkVersion</code> is to tell the Android system that it is
|
|
using APIs that were <em>introduced</em> in the API Level specified. If the
|
|
application were to be somehow installed on a platform with a lower API Level,
|
|
then it would crash at run-time when it tried to access APIs that don't exist.
|
|
The system prevents such an outcome by not allowing the application to be
|
|
installed if the lowest API Level it requires is higher than that of the
|
|
platform version on the target device.</p>
|
|
|
|
<p>For example, the {@link android.appwidget} package was introduced with API
|
|
Level 3. If an application uses that API, it must declare a
|
|
<code>android:minSdkVersion</code> attribute with a value of "3". The
|
|
application will then be installable on platforms such as Android 1.5 (API Level
|
|
3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and
|
|
Android 1.0 platforms (API Level 1).</p>
|
|
|
|
<p>For more information about how to specify an application's API Level
|
|
requirements, see the <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
|
|
section of the manifest file documentation.</p>
|
|
|
|
|
|
<h2 id="considerations">Development Considerations</h2>
|
|
|
|
<p>The sections below provide information related to API level that you should
|
|
consider when developing your application.</p>
|
|
|
|
<h3 id="fc">Application forward compatibility</h3>
|
|
|
|
<p>Android applications are generally forward-compatible with new versions of
|
|
the Android platform.</p>
|
|
|
|
<p>Because almost all changes to the framework API are additive, an Android
|
|
application developed using any given version of the API (as specified by its
|
|
API Level) is forward-compatible with later versions of the Android platform and
|
|
higher API levels. The application should be able to run on all later versions
|
|
of the Android platform, except in isolated cases where the application uses a
|
|
part of the API that is later removed for some reason. </p>
|
|
|
|
<p>Forward compatibility is important because many Android-powered devices
|
|
receive over-the-air (OTA) system updates. The user may install your
|
|
application and use it successfully, then later receive an OTA update to a new
|
|
version of the Android platform. Once the update is installed, your application
|
|
will run in a new run-time version of the environment, but one that has the API
|
|
and system capabilities that your application depends on. </p>
|
|
|
|
<p>In some cases, changes <em>below</em> the API, such those in the underlying
|
|
system itself, may affect your application when it is run in the new
|
|
environment. For that reason it's important for you, as the application
|
|
developer, to understand how the application will look and behave in each system
|
|
environment. To help you test your application on various versions of the Android
|
|
platform, the Android SDK includes multiple platforms that you can download.
|
|
Each platform includes a compatible system image that you can run in an AVD, to
|
|
test your application. </p>
|
|
|
|
<h3 id="bc">Application backward compatibility</h3>
|
|
|
|
<p>Android applications are not necessarily backward compatible with versions of
|
|
the Android platform older than the version against which they were compiled.
|
|
</p>
|
|
|
|
<p>Each new version of the Android platform can include new framework APIs, such
|
|
as those that give applications access to new platform capabilities or replace
|
|
existing API parts. The new APIs are accessible to applications when running on
|
|
the new platform and, as mentioned above, also when running on later versions of
|
|
the platform, as specified by API Level. Conversely, because earlier versions of
|
|
the platform do not include the new APIs, applications that use the new APIs are
|
|
unable to run on those platforms.</p>
|
|
|
|
<p>Although it's unlikely that an Android-powered device would be downgraded to
|
|
a previous version of the platform, it's important to realize that there are
|
|
likely to be many devices in the field that run earlier versions of the
|
|
platform. Even among devices that receive OTA updates, some might lag and
|
|
might not receive an update for a significant amount of time. </p>
|
|
|
|
<h3 id="platform">Selecting a platform version and API Level</h3>
|
|
|
|
<p>When you are developing your application, you will need to choose
|
|
the platform version against which you will compile the application. In
|
|
general, you should compile your application against the lowest possible
|
|
version of the platform that your application can support.
|
|
|
|
<p>You can determine the lowest possible platform version by compiling the
|
|
application against successively lower build targets. After you determine the
|
|
lowest version, you should create an AVD using the corresponding platform
|
|
version (and API Level) and fully test your application. Make sure to declare a
|
|
<code>android:minSdkVersion</code> attribute in the application's manifest and
|
|
set its value to the API Level of the platform version. </p>
|
|
|
|
<h3 id="apilevel">Declaring a minimum API Level</h3>
|
|
|
|
<p>If you build an application that uses APIs or system features introduced in
|
|
the latest platform version, you should set the
|
|
<code>android:minSdkVersion</code> attribute to the API Level of the latest
|
|
platform version. This ensures that users will only be able to install your
|
|
application if their devices are running a compatible version of the Android
|
|
platform. In turn, this ensures that your application can function properly on
|
|
their devices. </p>
|
|
|
|
<p>If your application uses APIs introduced in the latest platform version but
|
|
does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then
|
|
it will run properly on devices running the latest version of the platform, but
|
|
<em>not</em> on devices running earlier versions of the platform. In the latter
|
|
case, the application will crash at runtime when it tries to use APIs that don't
|
|
exist on the earlier versions.</p>
|
|
|
|
<h3 id="testing">Testing against higher API Levels</h3>
|
|
|
|
<p>After compiling your application, you should make sure to test it on the
|
|
platform specified in the application's <code>android:minSdkVersion</code>
|
|
attribute. To do so, create an AVD that uses the platform version required by
|
|
your application. Additionally, to ensure forward-compatibility, you should run
|
|
and test the application on all platforms that use a higher API Level than that
|
|
used by your application. </p>
|
|
|
|
<p>The Android SDK includes multiple platform versions that you can use,
|
|
including the latest version, and provides an updater tool that you can use to
|
|
download other platform versions as necessary. </p>
|
|
|
|
<p>To access the updater, use the <code>android</code> command-line tool,
|
|
located in the <sdk>/tools directory. You can launch the Updater by using
|
|
the <code>android</code> command without specifying any options. You can
|
|
also simply double-click the android.bat (Windows) or android (OS X/Linux) file.
|
|
In ADT, you can also access the updater by selecting
|
|
<strong>Window</strong> > <strong>Android SDK and AVD
|
|
Manager</strong>.</p>
|
|
|
|
<p>To run your application against different platform versions in the emulator,
|
|
create an AVD for each platform version that you want to test. For more
|
|
information about AVDs, see <a
|
|
href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. If
|
|
you are using a physical device for testing, ensure that you know the API Level
|
|
of the Android platform it runs. See the table at the top of this document for
|
|
a list of platform versions and their API Levels. </p>
|
|
|
|
|
|
<h2 id="provisional">Using a Provisional API Level</h2>
|
|
|
|
<p>In some cases, an "Early Look" Android SDK platform may be available. To let
|
|
you begin developing on the platform although the APIs may not be final, the
|
|
platform's API Level integer will not be specified. You must instead use the
|
|
platform's <em>provisional API Level</em> in your application manifest, in order
|
|
to build applications against the platform. A provisional API Level is not an
|
|
integer, but a string matching the codename of the unreleased platform version.
|
|
The provisional API Level will be specified in the release notes for the Early
|
|
Look SDK release notes and is case-sensitive.</p>
|
|
|
|
<p>The use of a provisional API Level is designed to protect developers and
|
|
device users from inadvertently publishing or installing applications based on
|
|
the Early Look framework API, which may not run properly on actual devices
|
|
running the final system image.</p>
|
|
|
|
<p>The provisional API Level will only be valid while using the Early Look SDK
|
|
and can only be used to run applications in the emulator. An application using
|
|
the provisional API Level can never be installed on an Android device. At the
|
|
final release of the platform, you must replace any instances of the provisional
|
|
API Level in your application manifest with the final platform's actual API
|
|
Level integer.</p>
|
|
|
|
|
|
<h2 id="filtering">Filtering the Reference Documentation by API Level</h2>
|
|
|
|
<p>Reference documentation pages on the Android Developers site offer a "Filter
|
|
by API Level" control in the top-right area of each page. You can use the
|
|
control to show documentation only for parts of the API that are actually
|
|
accessible to your application, based on the API Level that it specifies in
|
|
the <code>android:minSdkVersion</code> attribute of its manifest file. </p>
|
|
|
|
<p>To use filtering, select the checkbox to enable filtering, just below the
|
|
page search box. Then set the "Filter by API Level" control to the same API
|
|
Level as specified by your application. Notice that APIs introduced in a later
|
|
API Level are then grayed out and their content is masked, since they would not
|
|
be accessible to your application. </p>
|
|
|
|
<p>Filtering by API Level in the documentation does not provide a view
|
|
of what is new or introduced in each API Level — it simply provides a way
|
|
to view the entire API associated with a given API Level, while excluding API
|
|
elements introduced in later API Levels.</p>
|
|
|
|
<p>If you decide that you don't want to filter the API documentation, just
|
|
disable the feature using the checkbox. By default, API Level filtering is
|
|
disabled, so that you can view the full framework API, regardless of API Level.
|
|
</p>
|
|
|
|
<p>Also note that the reference documentation for individual API elements
|
|
specifies the API Level at which each element was introduced. The API Level
|
|
for packages and classes is specified as "Since <api level>" at the
|
|
top-right corner of the content area on each documentation page. The API Level
|
|
for class members is specified in their detailed description headers,
|
|
at the right margin. </p>
|