Developing Android applications is a unique experience, as it often involves taking advantage of the latest capabilities of Android while still providing backward compatibility to older Android devices in order to reach all potential users. This feat is accomplishable by using Android support libraries and doing runtime checks while using the latest APIs in the application code.
Android uses two specific properties set in the AndroidManifest.xml through the project properties to determine how your application should run. Thus, it is important to fully understand how these Android API settings impact your application.
Starting this year, Google Play will roll out a new policy that impacts all Android developers submitting new apps and app updates. This blog post will ensure that your application is fully ready for these changes, which will require the targetSdkVersion to be set to Android 8.0 API level 26 or higher, when it goes into effect for new apps on August 1, 2018 and for app updates on November 1, 2018.
Understanding API Levels
As mentioned earlier Android applications have two very important attributes that must be set in the AndroidManifest.xml file:
- Minimum Android Version (minSdkVersion): Specifies the oldest Android version that you want your app to support. This API level is used at runtime by Android.
- Target Android Version (targetSdkVersion): Specifies the version of Android that your app is intended to run on. This API level is used at runtime by Android.
An example would be the following:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.App15.Android">
<uses-sdk android:minSdkVersion="19" android:targetSdkVersion="27" />
The *uses-sdk* properties are used by the Android OS specifically to turn on or off features and by Google Play to determine what devices your application can run on. So for this example, the application can be installed on devices running Android 4.4 (KitKat API 19) and above, which is over 95% of all active Android devices. It also is informing Android that our application uses modern features of Android such as runtime permissions, adheres to background execution limits, and notification channels.
Google Play will require all applications to set the targetSdkVersion to API level 26 or higher so start testing today!
Update Compile (Target Framework) version
In addition to the two properties that are outlined above, there is one additional setting that must be updated for our application, which is the Compile framework. This is a specific Xamarin.Android property that is accessed in the Application properties that tells Xamarin.Android what Android framework to build the application against. This also impacts the APIs that you see when writing code inside of Visual Studio. When we right-click on an Android project and go to properties the Application settings will appear. It is recommended to use the latest version of Android (8.1 API 27 at the time of writing) and match both the Target SDK Version and Android support libraries versions, which we will see how to update later. This can be accomplished by simply setting the Compile using Android version: (Target Framework) property.
Do not worry if you do not have the Android 8.1 SDK installed. Easily install using the Android SDK Manager and installing Android SDK Platform 27:
This Target Framework is the equivalent of compileSdkVersion which informs aapt (Android Asset Packaging Tool) on what API level to use. This is why it is also important to update the Android Platform and Build tools to match your compilation target. This can be done from the Android SDK and Tools manager:
Update Target Android Version
Now, it is time to set the Target Android version which is what Google Play will start enforcing when submitting new apps and updates. Inside of the properties of the Android project, we will find the Android Manifest section which has both the Minimum and Target android versions.
IMPORTANT: These must be set to a specific version and cannot be set to “Use Compile Version”. Failure to set to a specific version number will result in the AndroidManifest.xml not getting the property assigned, which can cause several side effects.
To set it manually, simply select the same API Level of Android 8.1 (API Level 27 – Oreo) like so:
The Golden API Rule
All of these API and compile levels can get pretty confusing, but if you remember one thing it is the golden rule on how to set API levels:
minimumSdkVersion <= targetSdkVersion <= compileSdkVersion
Often this is even simplified because best practice is always to set the target and compile versions to the same. However, it is okay to have the targetSdkVersion set lower then the compileSdkVersion (Compile Target Framework).
Update Support Libraries
At this point, the app is ready to submit to Google Play and meets the new requirements, but we should also ensure that any Android support library is updated to the latest version. Android support libraries are versioned with the major number representing the version of Android SDK that it was compiled against, which means the latest version, 126.96.36.199, was compiled against Android SDK API 27 and is what our application should use. Opening the NuGet package manager will show us any Android support libraries that were installed that need to be updated. It is important to update all Android Support Libraries at the same time so they all match:
Handling NuGet Dependency API Level Conflicts
Most applications will also have additional libraries such as Xamarin.Essentials or third-party libraries that take a dependency on Android Support Libraries. If this is the case, ensure that you first manually add any of the Android Support Libraries to your Android project through NuGet before attempting to update all of them in your project. An example is Xamarin.Essentials which uses Xamarin.Android.Support.Core.Utils and Xamarin.Android.Support.CustomTabs. If these are not manually added to the project first you may see an error such as:
Version conflict detected for Xamarin.Android.Support.Compat. Reference the package directly from the project to resolve this issue.
App15.Android -> Xamarin.Android.Support.v7.MediaRouter 188.8.131.52 -> Xamarin.Android.Support.v7.Palette 184.108.40.206 -> Xamarin.Android.Support.Compat (= 220.127.116.11)
App15.Android -> Xamarin.Essentials 0.7.0.17-preview -> Xamarin.Android.Support.CustomTabs 27.0.2 -> Xamarin.Android.Support.Compat (= 27.0.2).
To get around the .csproj if using package references and at the same time manually update all support libraries to the latest version:
<PackageReference Include="Xamarin.Essentials" Version="0.7.0.17-preview" />
<PackageReference Include="Xamarin.Forms" Version="18.104.22.1682510" />
<PackageReference Include="Xamarin.Android.Support.Design" Version="22.214.171.124" />
<PackageReference Include="Xamarin.Android.Support.v7.AppCompat" Version="126.96.36.199" />
<PackageReference Include="Xamarin.Android.Support.v4" Version="188.8.131.52" />
<PackageReference Include="Xamarin.Android.Support.v7.CardView" Version="184.108.40.206" />
<PackageReference Include="Xamarin.Android.Support.v7.MediaRouter" Version="220.127.116.11" />
<PackageReference Include="Xamarin.Android.Support.CustomTabs" Version="18.104.22.168" />
<PackageReference Include="Xamarin.Android.Support.Core.Utils" Version="22.214.171.124" />
If the project still uses package references simply add the packages manually and then update all of the support libraries. You will want to do this with any other NuGet libraries that you may have.
Now your Android apps are up to date and ready for submission using the latest and greatest Android SDK and Support Libraries. To learn more about changes to Google Play requirements be sure to head over to the Android developer portal and for an in-depth overview of Android API level see our full documentation.
Have questions or comments? Discuss this post on the Xamarin forums!