Migrating to Android 8.0

Android 8.0 (API level 26) introduces behavior changes as well as new features and APIs that you can take advantage of in your apps. This document gives you an overview of the steps to migrate your apps to Android 8.0 across two key phases:

  1. Ensure compatibility with Android 8.0

    Verify that your app is fully functional on the new version of the platform. At this stage, you do not use new APIs or change your app's targetSdkVersion, but minor changes might be necessary.

  2. Update your target version and use Android 8.0 features

    When you are ready to take advantage of the new features of the platform, update your targetSdkVersion to 26, verify the app continues to function as expected, and then begin using new APIs.

Ensure compatibility with Android 8.0

The objective here is to make sure that your existing app works as-is on Android 8.0 (API level 26). Because some platform changes might affect the way your app behaves, some adjustments might be necessary, but you do not need to use new APIs or change your targetSdkVersion.

Ensure compatibility with Android 8.0 step-by-step

Prepare a device running Android 8.0

  • If you have a compatible device (Pixel, Pixel XL, Pixel C, Nexus 5X, Nexus 6P, or Nexus Player), follow the instructions to flash your device.
  • Or download the Android 8.0 system image for the Android Emulator. It's listed in the SDK Manager under Android 8.0 as Google APIs Intel x86 Atom System Image.

    Note: The Android 8.0 system image is available for download from Android Studio 3.0 and higher. For more information, see the section below to get the Android 8.0 SDK.

Perform compatibility testing

For the most part, testing compatibility with Android 8.0 (API level 26) entails the same type of testing you perform when preparing to release your app. This is a good time to review the Core App Quality Guidelines and Best Practices for Testing.

However, there's another aspect to testing: Android 8.0 introduces changes to the Android platform that can affect your app's behavior or break the app altogether, even if you do not change your targetSdkVersion. For this reason, it is important that you review the key changes in table 1, and test any fixes that you implement to accommodate the changes.

Table 1. Key changes that affect all apps running on Android 8.0 devices.

Change Summary Further reference
Less frequent background location updates If your app receives location updates from a background service, it receives less frequent updates on Android 8.0 (API level 26) compared to older versions of Android. Specifically, a background service cannot receive location updates more than a few times per hour. However, while your app is in the foreground, the rate of location updates is unchanged. Background Location Limits
net.hostname no longer supported Querying the net.hostname system property produces a null result. None
New exception from send(DatagramPacket) The send(DatagramPacket) method throws a SocketException if the previously executed connect(InetAddress, int) method failed. Behavior Changes: Network and HTTP(S) connectivity
Proper NullPointerException from AbstractCollection methods AbstractCollection.removeAll(null) and AbstractCollection.retainAll(null) now always throw a NullPointerException; previously, the NullPointerException was not thrown when the collection was empty. This change makes the behavior consistent with the documentation. Behavior Changes: Collection handling
Proper NullPointerException from Currency.getDisplayName(null) Calling Currency.getDisplayName(null) throws a NullPointerException. Behavior Changes: Locales and internationalization

For a more extensive list of behavior changes in Android 8.0 (API level 26), also see Android 8.0 Behavior Changes.

Update your target version and use Android 8.0 features

This section explains how to enable full support for Android 8.0 (API level 26) by updating your targetSdkVersion to 26 and adding new features available in Android 8.0.

In addition to offering you new APIs, Android 8.0 introduces some behavior changes when you update your targetSdkVersion to 26. Because some behavior changes might require code changes to avoid breakage, you should first understand how your app might be affected when you change the targetSdkVersion by reviewing all behavior changes for apps targeting Android 8.0.

Note: The steps described above to ensure platform compatibility are prerequisite to targeting your app to Android 8.0, so be sure you complete those steps first.

Update target version and use Android 8.0 features step-by-step

Get the Android 8.0 SDK

You can get the SDK packages to build your app with Android 8.0 (API level 26) using the latest version of Android Studio (Android Studio 3.0+ is recommended). Android Studio 3.0+ includes tools to help you with Android 8.0 features such as adaptive icons and downloadable fonts. If you don't need those features yet, then you can use the stable version of Android Studio 2.3.3 to build your app with Android 8.0 and use the new APIs.

To get set up with either version of Android Studio, follow these steps:

  1. Launch Android Studio and open the SDK Manager by clicking Tools > SDK Manager.
  2. In the SDK Platforms tab, check Show Package Details. Below Android 8.0 Preview check the following:
    • Android SDK Platform 26
    • Google APIs Intel x86 Atom System Image (only required for the emulator)
  3. Switch to the SDK Tools tab and check all items that have updates available (click each checkbox that shows a dash ). This should include the latest versions of the following items that are required:
    • Android SDK Build-Tools 26.0.0
    • Android SDK Platform-Tools 26.0.0
    • Android Emulator 26.0.0
  4. Click OK to install all the selected SDK packages.

Now you're ready to start building with Android 8.0.

Update your build configuration

Update compileSdkVersion, targetSdkVersion, and the Support Library version to the latest available revisions, for example: 

android {
  compileSdkVersion 26

  defaultConfig {
    targetSdkVersion 26
  }
  ...
}

dependencies {
  compile 'com.android.support:appcompat-v7:26.0.0'
}

// REQUIRED: Google's new Maven repo is required for the latest
// support library that is compatible with Android 8.0
repositories {
    google()

    // If you're using a version of Gradle lower than 4.1, you must instead use:
    // maven {
    //     url 'https://maven.google.com'
    // }
}

Remove broadcast receivers from your manifest file

Because Android 8.0 (API level 26) introduces new limitations for broadcast receivers, you should remove any broadcast receivers that are registered for implicit broadcast intents. Leaving them in place does not break your app at build-time or runtime, but they have no effect when your app runs on Android 8.0.

Broadcasts that only your app can respond to—Explicit broadcast intents and broadcasts sent to your app's package name specifically—continue to work the same on Android 8.0.

There are exceptions to this new restriction. For a list of implicit broadcasts that still work in apps targeting Android 8.0, see Implicit Broadcast Exceptions.

Test your Android 8.0 app

With the above preparations complete, you can build your app and then test it further to make sure it works properly when targeting Android 8.0 (API level 26). This is another good time to review the Core App Quality Guidelines and Best Practices for Testing.

When you build your app with the targetSdkVersion set to 26, there are specific platform changes you should be aware of. Some of these changes can significantly affect your app's behavior or even break your app altogether, even if you do not implement new features in Android 8.0.

Table 2 provides a list of these changes with links to more information.

Table 2. Key changes that affect apps when targetSdkVersion is set to 26.

Change Summary Further reference
Privacy Android 8.0 (API level 26) does not support use of the net.dns1, net.dns2, net.dns3, or net.dns4 system properties. Behavior Changes: Privacy
Writable and Executable Segments Enforced For native libraries, Android 8.0 (API level 26) enforces the rule that data shouldn’t be executable, and code shouldn’t be writable. Behavior Changes: Native Libraries
ELF header and section validation The dynamic linker checks more values in the ELF header and section headers, and fails if they are invalid. Behavior Changes: Native Libraries
Notifications Apps targeting the Android 8.0 (API level 26) version of the SDK must implement one or more notification channels to post notifications to users. API Overview: Notifications
The List.sort() method Implementations of this method may no longer call Collections.sort(), or your app will throw an exception due to stack overflow. Behavior Changes: Collection handling
The Collections.sort() method In List implementations, Collections.sort() now throws a ConcurrentModificationException. Behavior Changes: Collection handling

For a more extensive list of behavior changes in Android 8.0 (API level 26), see Android 8.0 Behavior Changes.

To explore the new features and APIs available with Android 8.0 (API level 26), see Android 8.0 Features and APIs.