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