Understanding Android API Levels

PDF for offline use
Related Links:

Let us know how you feel about this


0/250

last updated: 2016-12

Xamarin.Android has several Android API level settings that determine your app's compatibility with multiple versions of Android. This guide explains what these settings mean, how to configure them, and what effect they have on your app at run time.

Overview

This guide describes how Android uses API levels to manage app compatibility across different versions of Android, and it explains how to configure Xamarin.Android project settings to deploy these API levels in your app. In addition, this guide explains how to write runtime code that deals with different API levels, and it provides a table that relates API levels to Android version numbers (such as Android 4.1), Android version names (such as Jelly Bean), and build version codes.

Quick Start

Xamarin.Android exposes three Android API level project settings:

  • Target Framework – Specifies which framework to use in building your application. This API level is used at compile time by Xamarin.Android.

  • Minimum Android Version – Specifies the oldest Android version that you want your app to support. This API level is used at run time by Android.

  • Target Android Version – Specifies the version of Android that your app is intended to run on. This API level is used at run time by Android.

Before you configure these settings, be sure to install the necessary Android SDK packages that you will need for your project. See Android SDK Platform Settings for information about using the Android SDK Manager to install SDK packages.

Normally, all three Xamarin.Android API levels are set to the same value. Set Compile using Android version (the target framework setting) to the Android version that has all of the features you need, then set the minimum and target Android versions to Use Compile using SDK version (which tracks the target framework setting) as shown here:

If you want to maintain backward compatibility with an earlier version of Android, change Minimum Android version to target to the oldest version of Android that you want your app to support. The following example configuration supports Android versions from API Level 14 thru API level 21:

Normally, all three Xamarin.Android API levels are set to the same value. Set Target framework to the Android version that has all of the features you need:

Set the minimum and target Android versions to Automatic - use target framework version as shown here:

If you want to maintain backward compatibility with an earlier version of Android, change Minimum Android version to the oldest version of Android that you want your app to support. For example, the following configuration supports Android versions as early as API Level 14:

If your app supports multiple Android versions, your code must include runtime checks to ensure that your app works with your minimum Android version setting (see Runtime Checks for Android Versions below for details). If you are consuming or creating a library, see API Levels and Libraries for best practices in configuring API level settings for libraries.

Android Versions

As the Android platform evolves and new Android versions are released, each Android version is assigned a unique integer identifier, called the API Level. Because users install apps on older as well as the most recent versions of Android, real-world Android apps must be designed to work with multiple Android API levels.

Each release of Android goes by multiple names:

  • The Android version, such as Android 4.4
  • The API level, such as "API Level 19"
  • A dessert name, such as "KitKat"

In addition, Xamarin.Android defines build version codes that map to the currently known Android API levels. The following table can help you translate between Android version, API level, the dessert name, and the build version code.

Android Version Released API Level Name Build Version Code
Android 7.1 December 2016 25 Nougat Android.OS.BuildVersionCodes.NMr1
Android 7.0 August 2016 24 Nougat Android.OS.BuildVersionCodes.N
Android 6.0 August 2015 23 Marshmallow Android.OS.BuildVersionCodes.M
Android 5.1 March 2015 22 Lollipop Android.OS.BuildVersionCodes.LollipopMr1
Android 5.0 November 2014 21 Lollipop Android.OS.BuildVersionCodes.Lollipop
Android 4.4W June 2014 20 Kitkat Watch Android.OS.BuildVersionCodes.KitKatWatch
Android 4.4 October 2013 19 Kitkat Android.OS.BuildVersionCodes.KitKat
Android 4.3 July 2013 18 Jelly Bean Android.OS.BuildVersionCodes.JellyBeanMr2
Android 4.2-4.2.2 November 2012 17 Jelly Bean Android.OS.BuildVersionCodes.JellyBeanMr1
Android 4.1-4.1.1 June 2012 16 Jelly Bean Android.OS.BuildVersionCodes.JellyBean
Android 4.0.3-4.0.4 December 2011 15 Ice Cream Sandwich Android.OS.BuildVersionCodes.IceCreamSandwichMr1
Android 4.0-4.0.2 October 2011 14 Ice Cream Sandwich Android.OS.BuildVersionCodes.IceCreamSandwich
Android 3.2 June 2011 13 Honeycomb Android.OS.BuildVersionCodes.HoneyCombMr2
Android 3.1.x May 2011 12 Honeycomb Android.OS.BuildVersionCodes.HoneyCombMr1
Android 3.0.x February 2011 11 Honeycomb Android.OS.BuildVersionCodes.HoneyComb
Android 2.3.3-2.3.4 February 2011 10 Gingerbread Android.OS.BuildVersionCodes.GingerBreadMr1
Android 2.3-2.3.2 November 2010 9 Gingerbread Android.OS.BuildVersionCodes.GingerBread
Android 2.2.x June 2010 8 Froyo Android.OS.BuildVersionCodes.Froyo
Android 2.1.x January 2010 7 Eclair Android.OS.BuildVersionCodes.EclairMr1
Android 2.0.1 December 2009 6 Eclair Android.OS.BuildVersionCodes.Eclair01
Android 2.0 November 2009 5 Eclair Android.OS.BuildVersionCodes.Eclair
Android 1.6 September 2009 4 Donut Android.OS.BuildVersionCodes.Donut
Android 1.5 May 2009 3 Cupcake Android.OS.BuildVersionCodes.Cupcake
Android 1.1 February 2009 2 Base Android.OS.BuildVersionCodes.Base11
Android 1.0 October 2008 1 Base Android.OS.BuildVersionCodes.Base

As this table indicates, new Android versions are released frequently – sometimes several releases per year. As a result, the universe of Android devices that might run your app includes of a wide variety of older and newer Android versions. How can you guarantee that your app will run consistently and reliably on so many different versions of Android? Android's API levels can help you manage this problem.

Android API Levels

Each Android device supports exactly one API level – this API level is guaranteed to be unique per Android platform version. The API level exactly identifies the version of the libraries that your app can call into; it identifies the combination of manifest elements, permissions, etc. that you code against as a developer. Android's system of API levels helps Android determine whether an application is compatible with an Android system image prior to installing the application on a device. When an application is built, it contains the following API level information:

  • The target API level of Android that the app is built to run on.
  • The minimum API level of Android that is required to run the app.

These settings are used to ensure that the functionality needed to run the app correctly is available on the Android device at installation time. If not, the app is blocked from running on that device. For example, if the API level of an Android device is lower than the minimum API level that you specify for your app, the Android device will prevent the user from installing your app.

Project API Level Settings

The following sections explain how to use the Android SDK Manager to prepare your development environment for the API levels you want to target, followed by detailed explanations of how to configure target framework, minimum Android version, and target Android version settings in Xamarin.Android.

Android SDK Platform Settings

Before you can select a target or minimum API level in Xamarin.Android, you must install the Android SDK version that corresponds to that API level. The range of available choices for target framework, minimum Android version, and target Android version is limited to the range of Android SDK versions that you have installed. You can use the Android SDK Manager to verify that the required Android SDK versions are installed, and you can use it to add any new API levels that you need for your app.

Start the Android SDK Manager (in Visual Studio, Tools > Android > Start Android SDK Manager). The Android SDK Manager lists the installed Android API levels as shown here:

The SDK Platform for your target framework API level should be marked as Installed. For example, in the above screenshot, the SDK platform for Android 4.4.2 (API Level 19) is marked as Installed, but the SDK platform for Android 4.1.2 (API 16) is marked as Not Installed. If the SDK platform for your target or minimum API level is not installed:

Start the Android SDK Manager (in Xamarin Studio, Tools > Open Android SDK Manager). The Android SDK Manager lists the installed Android API levels as shown here:

The SDK Platform for your target framework API level should be marked as Installed. For example, in the above screenshot, the SDK platform for Android 4.4.2 (API Level 19) is marked as Installed, but the SDK platform for Android 4.0 (API Level 14) is marked as Not Installed. If the SDK platform for your target or minimum API level is not installed:
  1. Enable the check box next to the SDK platform for the API level that you want to use (along with any system images for that API level that you want to use for testing).

  2. Click Install N Packages (N is displayed as the total number of packages to install).

  3. Click Android SDK License in the Packages column.

  4. Click Accept License if you accept the Android SDK terms and conditions.

  5. Click Install.

Target Framework

The target framework is the specific Android framework version (API level) that your app is compiled for at build time. This setting specifies what APIs your app expects to use when it runs, but it has no effect on which APIs are actually available to your app when it is installed. The target framework and the target Android version, while having very similar names, are not the same thing. The target framework setting communicates target API level information to Xamarin.Android for use at compile time, while the target Android version communicates target API level information to Android for use at run time (when the app is installed and running on a device).

The target framework identifies which library versions your application is linked against – this determines which APIs you can use in your app. For example, if you want to use the new NotificationBuilder.SetCategory method that was introduced in Android 5.0 Lollipop, you must set the target framework to API Level 21 (Lollipop). If you set your project's target framework to an API level such as API Level 19 (KitKat) and try to call the SetCategory method in your code, you will get a compile error.

To access the target framework setting in Visual Studio, open the project properties in Solution Explorer and select the Application page:

Set the target framework by selecting an API level in the drop-down menu under Compile using Android version as shown above.

To access the target framework setting in Xamarin Studio, click the gray gear icon to the right of the project and select Options; this opens the Project Options dialog. In this dialog, click Build > General as shown here:

Set the target framework by selecting an API level in the drop-down menu to the right of Target framework as shown above.

Minimum Android Version

The minimum Android version is the oldest version of Android (lowest API level) that can install and run your application. By default, an app can only be installed on devices matching the target framework setting or higher; if the minimum Android version setting is lower than the target framework setting, your app can also run on earlier versions of Android. For example, if you set the target framework to Android 5.0 Lollipop and set the minimum Android version to Android 4.0.3 (Ice Cream Sandwich), your app can be installed on any platform from API level 15 to API level 21, inclusive.

Although your app may successfully build and install on this range of platforms, this does not guarantee that it will successfully run on all of these platforms. For example, if your app is installed on Android 4.0.3 (Ice Cream Sandwich) and your code calls an API that is available only in Android 5.0 (Lollipop) and newer, your app will get a runtime error and possibly crash. Therefore, your code must ensure – at runtime – that it calls only those APIs that are supported by the Android device that it is running on. In other words, your code must include explicit runtime checks to ensure that your app uses newer APIs only on devices that are recent enough to support them. Runtime Checks for Android Versions, later in this guide, explains how to add these runtime checks to your code.

To access the minimum Android version setting in Visual Studio, open the project properties in Solution Explorer and select the Application page. In the drop-down menu under Minimum Android to target you can select the minimum Android version for your application:

If you select Use Compile using SDK version (as shown), the minimum Android version will be the same as the target framework setting.

To access the minimum Android version setting in Xamarin Studio, click the gray gear icon to the right of the project and select Options; this opens the Project Options dialog. Click Build > Android Application. Using the drop-down menu to the right of Minimum Android version, you can set the minimum Android version for your application:

If you select Automatic – use target framework version (as shown), the minimum Android version will be the same as the target framework setting.

Target Android Version

The target Android version is the API level of the Android device where the app expects to run. Android uses this setting to determine whether to enable any compatibility behaviors – this ensures that your app continues to work the way you expect.

To access this setting in Visual Studio, open the project properties in Solution Explorer and select the Application page. In the drop-down menu under Target Android version you can select the target Android version for your application:

Normally, you should leave the target Android version set to Use Compile using SDK version (as shown) so that its value automatically matches the target framework setting.

To access this setting in Xamarin Studio, click the gray gear icon to the right of the project and select Options; this opens the Project Options dialog. Click Build > Android Application. Using the drop-down menu to the right of Target Android version, you can set the target Android version for your application:

Normally, you should leave the target Android version set to Automatic - use target framework version (as shown) so that its value automatically matches the target framework setting.

In general, the Target Android Version should be bounded by the Minimum Android Version and the Target Framework. That is:

  • Minimum Android Version ≤ Target Android Version ≤ Target Framework

For more information about SDK levels, see the Android uses-sdk documentation.

Runtime Checks for Android Versions

As each new version of Android is released, the framework API is updated to provide new or replacement functionality. With few exceptions, API functionality from earlier Android versions is carried forward into newer Android versions without modifications. As a result, if your app runs on a particular Android API level, it will typically be able to run on a later Android API level without modifications. But what if you also want to run your app on earlier versions of Android?

If you select a minimum Android version that is lower than your target framework setting, some APIs may not be available to your app at runtime. However, your app can still run on an earlier device, but with reduced functionality. For each API that is not available on Android platforms corresponding to your minimum Android version setting, your code must explicitly check the value of the Android.OS.Build.VERSION.SdkInt property to determine the API level of the platform the app is running on. If the API level is lower than the minimum Android version that supports the API you want to call, then your code has to find a way to function properly without making this API call.

For example, let's suppose that we want to use the new NotificationBuilder.SetCategory method to categorize a notification when running on Android 5.0 Lollipop (and later), but we still want our app to run on earlier versions of Android such as Android 4.1 Jelly Bean (where SetCategory is not available). Referring to the Android version table at the beginning of this guide, we see that the build version code for Android 5.0 Lollipop is Android.OS.BuildVersionCodes.Lollipop. To support older versions of Android where SetCategory is not available, our code can detect the API level at runtime and conditionally call SetCategory only when the API level is greater than or equal to the Lollipop build version code:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) 
{
    builder.SetCategory(Notification.CategoryEmail);
}

In this example, our app's target framework is set to Android 5.0 (API Level 21) and its minimum Android version is set to Android 4.1 (API Level 16). Because SetCategory is available in API level Android.OS.BuildVersionCodes.Lollipop and later, this example code will call SetCategory only when it is actually available – it will not attempt to call SetCategory when the API level is 16, 17, 18, 19, or 20. The functionality is reduced on these earlier Android versions only to the extent that notifications are not sorted properly (because they are not categorized by type), yet the notifications are still published to alert the user. Our app still works, but its functionality is slightly diminished.

In general, the build version check helps your code decide at runtime between doing something the new way versus the old way. For example:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) 
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

There's no fast and simple rule that explains how to reduce or modify your app's functionality when it runs on older Android versions that are lacking one or more APIs. In some cases (such as in the SetCategory example above), it's sufficient to simply omit the API call when it's not available. However, in other cases, you may need to implement alternate functionality for when Android.OS.Build.VERSION.SdkInt is detected to be less than the API level that your app needs to present its optimum experience.

API Levels and Libraries

When we create a Xamarin.Android library project (such as a class library or a bindings library), we can configure only the target framework setting – the minimum Android version and the target Android version settings are not available:

When we create a Xamarin.Android library project, there is no Android Application page where we can configure the minimum Android version and the target Android version – the minimum Android version and target Android version settings are not available:

The minimum Android version and target Android version settings are omitted because the resulting library is not a stand-alone app – the library could be run on any Android version, depending on the app that it is packaged with. We can specify how the library is to be compiled, but we can't predict which platform API level the library will be run on. With this in mind, the following best practices should be observed when consuming or creating libraries:

  • When consuming an Android library – If you are consuming an Android library in your application, be sure to set your app's target framework setting to an API level that is at least as high as the target framework setting of the library.

  • When creating an Android library – If you are creating an Android library for use by other applications, be sure to set its target framework setting to the minimum API level that it needs in order to compile.

These best practices are recommended to help prevent the situation where a library attempts to call an API that is not available at runtime (which can cause the app to crash). If you are a library developer, you should strive to restrict your usage of API calls to a small and well-established subset of the total API surface area. Doing so helps to ensure that your library can be used safely across a wider range of Android versions.

Summary

This guide explained how Android API levels are used to manage app compatibility across different versions of Android. It provided detailed steps for configuring the Xamarin.Android target framework, minimum Android version, and target Android version project settings. It provided instructions for using the Android SDK Manager to install SDK packages, included examples of how to write code to deal with different API levels at runtime, and explained how to manage API levels when creating or consuming Android libraries. It also provided a comprehensive table that relates API levels to Android version numbers (such as Android 4.4), Android version names (such as Kitkat), and Xamarin.Android build version codes.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.