Peter_vdL

API Levels and You

by Peter_vdL Motorola 01-04-2012 07:38 PM - edited 07-25-2012 08:57 AM

Just about every AndroidManifest.xml file contains a "<uses-sdk>" element.  The element describes how compatible your app is with the different API levels.   You can describe up to three aspects of your app:


  • the minimum API level needed for the application to run.  If you don't provide it explicitly, the default value is "1" meaning the app runs on all versions of Android.  Using something from a later API will result in a runtime failure on an API level 1 phone.
  • the highest tested API level on which you have run the app.  With traditional Android naming slackness, this is called the "targeted SDK level".  By providing this value, you can avoid complicated small-screen and low-resolution forward-compatibility features.  Newer Android releases provide backward compatability for older apps.  By setting the targeted SDK level, you tell newer phones not to emulate older hardware when running your app.  This is becoming less relevant as low end phones with old releases gradually die off.
  • the maximum API level where your app will run.  This attribute was not well thought out, and it actually caused apps to be uninstalled from your device when a system upgrade moved the phone API level past an app's maximum API level!  App loss is a very undesirable side effect of a FOTA upgrade.  The attribute was introduced in API level 4, then deprecated and ignored from API level 7.  Android supports good backwards compatibility (older apps run on newer devices) so there was no real reason for this attribute at all.
The syntax of the "<uses-sdk>" element within the manifest is:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" .... >

     <uses-permission ...  />

     <application ...>
             <activity ...>
             </activity>
      </application>

     <uses-sdk
          android:minSdkVersion="integer”
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

</manifest>

 

The different elements, "<application>" and so on, may come in any order.  Integer values for the API levels (sdk versions) are shown in this table:

 

Platform Version

API Level

Name

New features

Android 4.1.x

16

Jelly Bean

Performance, better notifications, Renderscript graphics deprecated (and thus Gallery widget deprecated), encryption of paid apps in Google play,

Android 4.0.3, 4.0.4

15

Ice Cream Sandwich maintenance release 1, 2

Tools for network data use management, merge of tablet and phone code bases, gallery has a photo editor, hardware button to take a screen snapshot and store it locally

Android 4.0, 4.0.1, 4.0.2

14

Ice Cream Sandwich  

Android 3.2

13

Honeycomb maintenance release 2

 

Android 3.1.x

12

Honeycomb maintenance release 1

USB host API, Media Transfer Protocol API, resizable home screen widgets

Android 3.0.x

11

Honeycomb

tablet UI, fragments, improved support for central device administration

Android 2.3.4

Android 2.3.3

10

Gingerbread maintenance release 1

multi touch "key chording" on text input, more aggressive power management, a shortcut to "manage apps" in the home screen options menu , support for SIP calling, support for multiple cameras, NFC support

Android 2.3.2

Android 2.3.1

Android 2.3

9

Gingerbread

 

Android 2.2.x

8

Froyo

support for Microsoft's Exchange protocols, Android Cloud to Device Messaging, multiple keyboard languages, the new Stagefright media-playing frame work, Linux kernel 2.6.32

Android 2.1.x

7

Eclair maintenance release 1

improved software keyboard, search feature for saved SMS messages, email support for Microsoft Exchange, support for double tap zoom in browser, some html5 support, New APIs for sync adapters to connect to any backend, new AccountManager APIs

Android 2.0.1

6

Eclair_0_1

 

Android 2.0

5

Eclair

 

Android 1.6

4

Donut

text to speech engine, new search box, accessibility framework, support for CDMA phones, linux kernel upgrade to 2.6.29

Android 1.5

3

Cupcake

UI refinements, performance improvements


 

There were two earlier Android versions, code-named "Astro Boy" and "Bender".   The names of all popular robots are trademarked by other people, so Google switched to a sweets theme for the public releases.  We can speculate about possibilities for future releases, like this:

Platform Version

API Level

Name

New features

Android 4.1

16

Jello shots

real time natural language speech translator (early access)

Android 4.2

17

Kahlua torte

anti-gravity API, DWIM button

Android 5.0

18

Lemon meringue pie

time travel API


 

But that's just wishful thinking about what I'd like to see.  How do you decide what SDK values to use?  Don't use maxSdkVersion at all.  The targetSdkVersion is also easy - just use the API level of the platform that you're developing on (or any higher level that you test on).

The ICS statue eclipses the Honeycomb statue, in the swamp outside building 44 on the Googleplex.

 

Set the minSdkVersion as low as you can, while still using an API level that has the features you need.  If your app uses the USB host API, you've got to set minSdkVersion to 12 or later, because that's when the USB host API was introduced.  The lower the minSdkVersion number, the larger the population of handsets that can run your app.   And you want to maximize the number of handsets that can run your app, to avoid needlessly losing users.  The android market looks at the API level of a phone to decide which apps it will even offer to that user.  The documentation on the Android Developers site offers a "Filter by API Level" control in the top-right area of each page, so it's easy to check when an API first appeared.

 

There's also the issue of "how many handsets are still out there?" for older handsets.  Fortunately Google keeps statistics on that, based on the API level of phones accessing the Android Market over two week periods.   You can find their statistics here, and they are updated regularly.   Cupcake and Donut account for just 2.1% of the installed base at the time of writing (early 2012), making it an easy decision to include or exclude them without a significant impact on app sales.

 

There's more about "uses-SDK" here, but the above covers it for most developers.

 

Peter van der Linden

Android Technology Evangelist



Post a Comment
Be sure to enter a unique name. You can't reuse a name that's already in use.
Be sure to enter a unique email address. You can't reuse an email address that's already in use.
reCAPTCHA challenge image
Type the characters you see in the picture above.Type the words you hear.
MOTODEV for Enterprise
Welcome...

Comment on our blog and tell us how we can help you build and distribute enterprise mobile applications on Motorola devices.

Subscribe to our RSS feed Subscribe via RSS

Follow Us

Our Blog & Comment Policy
Opinions expressed here and in any corresponding comments are the personal opinions of the original authors, not of Motorola. The content is provided for informational purposes only and is not meant to be an endorsement or representation by Motorola or any other party.

Remember, when you comment, please stay on topic and avoid spam, profanity, and anything else that violates our user guidelines. All comments require approval by Motorola and can be rejected for any reason.

For customer support issues with your Motorola phone go to the Motorola customer support website.
Blogroll