Android Essentials: Making Sense of Android Versioning

Cupcake, Donut, Éclair, Froyo, Gingerbread, Honeycomb, Ice Cream Sandwich… Perhaps you’ve heard Android developers talking about these platform code-names and wondered how to keep track of all these different versions of the Android platform. In this tutorial, you’ll learn everything you need to know about Android platform versioning.

The Android platform is constantly evolving. Developers who want to write Android applications for specific devices need to be aware of the platform versions they need to support, and how to achieve this.

How Android Versioning Works

Android platform versions are labeled in a number of ways: by version number, by code-name, and by API level.

The version number is a traditional, incremental version associated with the progress of the platform. For example, the first official Android release was Android 1.0. The next minor release was Android 1.1, and so on. Android releases vary in importance. A very minor release may receive an increment of a tenth or even a hundredth. A major release usually increments by a whole number. E.g. 2.0.
The code-name is a friendly name associated with a substantive update to the platform and corresponds to a specific Android version or range of versions. The first two releases of the Android platform did not have official (and external) code-names, but each important subsequent version has, regardless of whether it was a whole numbered version or not. The code-names are alphabetical and tied to sweets like Cupcakes, Donuts, and, most recently, Ice Cream Sandwiches. Minor releases or updates do not receive codenames, but retain the prior code-name and are labeled with MR. For example, Honeycomb (Android 3.0) was released in Feb. 2011, Honeycomb MR1 (Android 3.1) was released in May of the same year.
The API Level is a number that identifies which Android SDK revision (set of APIs) is compatible with a specific Android platform version. As the Android platform has matured, so has the Android SDK. New classes, methods, and features have been added to the platform over time. Each new class or method specifies the API Level in which it was introduced. These features are only accessible to applications that target devices that run a platform version that matches the API Level or higher.

Android 1.0 corresponds to API Level 1. This first official version of the Android platform did not have a code-name.
Android 1.1 corresponds to API Level 2. This second official version of the Android platform did not have a code-name.
Android 1.5 corresponds to API Level 3. This version of the Android platform was code-named Cupcake.
Android 1.6 corresponds to API Level 4. This version of the Android platform was code-named Donut.
Android 2.0 corresponds to API Level 5. This version of the Android platform was code-named Eclair.
Android 2.0.1 corresponds to API Level 6. This version of the Android platform was code-named Eclair _0_1.
Android 2.1.X versions correspond to API Level 7. These versions of the Android platform were code-named Eclair MR1.
Android 2.2.X versions correspond to API Level 8. These versions of the Android platform were code-named Froyo.
Android 2.3, 2.3.1 and 2.3.2 correspond to API Level 9. These versions of the Android platform were code-named Gingerbread.
Android 2.3.3 and 2.3.4 correspond to API Level 10. These versions of the Android platform were code-named Gingerbread MR1.
Android 3.0.X versions correspond to API Level 11. These versions of the Android platform were code-named Honeycomb.
Android 3.1.X versions correspond to API Level 12. These versions of the Android platform were code-named Honeycomb MR1.
Android 3.2.X versions correspond to API Level 13. These versions of the Android platform were code-named Honeycomb MR2.
Android 4.0 (anticipated Fall 2011) will likely correspond to API Level 14. The next version of the Android platform has been code-named Ice Cream Sandwich.

Not only do Android versions have names, versions, and API Levels… they also have logos!

For more information on platform versions, API Levels, and code-names, see the Android API Levels appendix in the Android SDK documentation.

Specifying the Android Application SDK Target Range

Android applications are compiled against a specific version of the Android SDK, as determined in the project settings when the project is created or updated. The platform target is also defined in the Android manifest file associated with a given application, using the API Level value.
Developers can use the tag to specify the Android platform versions supported by the application. This tag has three attributes:

android:minSdkVersion: The minimum Android platform version supported by the application, specified as an API Level. While the application is not compiled against this version of the Android SDK, developers should use this attribute to indicate compatibility. If this value is not set, the assumption is that the application is compatible with all versions of the Android SDK. Using this attribute is highly recommended.
android:targetSdkVersion: The target Android platform version supported by the application, specified as an API Level. This is usually the version of the Android SDK compiled against and used to indicate the version the developer primarily tested and designed for. Using this attribute is highly recommended.
android:maxSdkVersion: The maximum Android platform version supported by the application, specified as an API Level. Using this attribute is not recommended for a variety of reasons and is being phased out.

Generally speaking, most developers will want to support as many different devices as possible with a single application package file. This means setting the broadest range of API Levels for the minSdkVersion and targetSdkVersion. However, if you specify that your application is compatible with a given version, make certain it really is! How do you know? Well, you’ll need to ensure that you only use Android SDK features that were introduced at the minSdkVersion API Level or lower. We’ll discuss how you determine this in a moment.

What versions are worth supporting? Knowing the most popular device versions on the market today can help you make this decision (Figure 2).

You can find the latest information, which is usually updated about every two weeks, on the Android developer website.

Don’t I Just Want to Target the Latest Android SDK?

Developers new to the platform often jump in and install the latest Android tools and Android SDK and think that everything will just work on all devices. This is not the case.

Every Android SDK feature, whether it’s a class, interface, method, constant or what have you, was introduced in a specific version of the SDK (specified by API Level). Therefore, you must ensure that your application only uses Android SDK features that correspond to the minSdkVersion API Level and lower. For instance, if you claim that your application is compatible with Android 1.6, or API Level 4, then you cannot use the dispatchGenericMotionEvent() method of the Activity class (http://developer.android.com/reference/android/app/Activity.html#dispatchGenericMotionEvent(android.view.MotionEvent), which was introduced in API Level 12, or Android 3.1. Note: there are ways to conditionally use different Android SDK methods at runtime but these techniques are beyond the scope of this beginner tutorial.

How Do I Know the API Level of an Android SDK Feature?

The Android API Level is listed in the Android SDK documentation. For classes and interfaces, the API Level is listed in the top right corner of the class reference documentation, as shown in Figure 3.

For constants, constructors, methods, and the like, the API level is listed on the far right of the descriptive write-up for the item, as shown in Figure 4.

By default, the Android SDK documentation displays API classes, methods and otherwise for all versions of the Android platform. However, you can filter the online documentation by API Level by setting the “Filter by API Level” setting at the top right-hand corner on the Reference tab of the Android Developer’s website documentation, as shown in Figure 5. API features that were introduced after that API Level will be grayed out.

Determining the Android Version of a Device

Android devices run a specific version of the platform. However, this version number can change over time, when carriers and operators push out over-the-air firmware upgrades to specific devices.

You cannot rely on a specific device always having a specific Android version. Different carriers may carry the same device, but roll out updates at different intervals, or not at all!

As a device user, you can determine the version of the Android platform by launching the Settings application, clicking “About phone” or “About tablet” (depends on your device type), and checking the value of the Android version setting. This will give you the Android platform version that is currently running on the device.

As a developer, you can programmatically check the Android platform version at runtime using the android.os.Build.VERSION class. See its class documentation for more details.

Conclusion

Android devices run different versions of the Android SDK. Versions are referred to by version number, code-name, and API Level. Developers need to be aware of what features of the Android SDK they are using to build their applications, as these design decisions affect what versions of the Android platform their application will be compatible with.

About the Authors

Mobile developers Lauren Darcey and Shane Conder have coauthored several books on Android development: an in-depth programming book entitled Android Wireless Application Development, Second Edition and Sams Teach Yourself Android Application Development in 24 Hours, Second Edition. When not writing, they spend their time developing mobile software at their company and providing consulting services. They can be reached at via email to [email protected], via their blog at androidbook.blogspot.com, and on Twitter @androidwireless.