MOTODEV For Enterprise

[#1]

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