Meet Google Play's target API level requirement

When you upload an APK, it must meet Google Play’s target API level requirements.

Starting on August 31, 2023:

  • New apps must target Android 13 (API level 33) or higher; except for Wear OS apps, which must target a version between Android 11 (API level 30) and Android 13 (API level 33), inclusive.

  • App updates must target Android 13 or higher and adjust for behavioral changes in Android 13; except for Wear OS apps, which must target Android 11.

Permanently private apps—which are restricted to users in a specific organization and are intended for internal distribution only—aren't required to meet the target API level requirements.

Note: Starting in 2022, some out-of-date apps will be unavailable to new users of devices that run newer versions of Android.

Why target newer SDKs?

Every new Android version introduces changes that bring security and performance improvements and enhance the Android user experience. Some of these changes only apply to apps that explicitly declare support through their targetSdkVersion manifest attribute (also known as the target API level).

Configuring your app to target a recent API level ensures that users can benefit from these improvements, while your app can still run on older Android versions. Targeting a recent API level also allows your app to take advantage of the platform's latest features to delight your users. Furthermore, as of Android 10 (API level 29), users see a warning when they start an app for the first time if the app targets Android 5.1 (API level 22) or lower.

This document highlights important points you need to know in updating your target API level to meet the Google Play requirement.

When migrating from lower versions, please see the full list of changes below.

Note: If your Gradle file contains manifest entries, you can confirm or change the current value of targetSdkVersion in your app's Gradle file, as described in Configure your build. Alternatively, you can use the android:targetSdkVersion attribute in the manifest file, as described in the documentation for the <uses-sdk> manifest element.

Migrate from Android 12 (API level 31) to Android 13 (API level 33)

To update your app to target Android 13 follow the behavior changes list.

Migrate from Android 11 (API level 30) to Android 12 (API level 31)

Security and Permissions

User Experience

  • Custom notifications: Notifications with custom content views will no longer use the full notification area; instead, the system applies a standard template. This template ensures that custom notifications have the same decoration as other notifications in all states. This behavior is nearly identical to the behavior of Notification.DecoratedCustomViewStyle.
  • Android App Links verification changes: When using Android App Link verification, make sure that your intent filters include the BROWSABLE category and support the HTTPS scheme.

Performance

  • Foreground service launch restrictions: To target Android 12 or higher, your app can't start foreground services while it runs in the background, except for a few special cases. If an app attempts to start a foreground service while running in the background, an exception occurs (except for the few special cases).

    Consider using WorkManager to schedule and start expedited work while your app runs in the background. To complete time-sensitive actions that the user requests, start foreground services within an exact alarm.

  • Notification trampoline restrictions: When users tap notifications, some apps respond by launching an app component that starts the activity that the user sees and interacts with. This app component is known as a notification trampoline.

    Apps must not start activities from services or broadcast receivers that are used as notification trampolines. After a user taps on a notification or action button within the notification, your app cannot call startActivity() inside of a service or broadcast receiver.

View the complete set of changes that affect apps targeting Android 12 (API level 31).

Migrating from lower than Android 11 (API level 30)

Select the version of Android you will be migrating from:

Migrate to Android 5 (API level 21)

See the respective Behavior Changes page for each of the following releases to ensure your that your app has accounted for changes introduced in these releases:

Continue by following the instructions in the next section.

Migrate to Android 6 (API level 23)

The following considerations apply to apps targeting Android 6.0 and higher versions of the platform:

  • Runtime Permissions

    • Dangerous permissions are only granted at runtime. Your UI flows must provide affordances for granting these permissions.

    • Wherever possible, ensure your app is prepared to handle rejection of permission requests. For example, if a user declines a request to access the device's GPS, ensure your app has another way to proceed.

For an exhaustive list of changes introduced in Android 6.0 (API level 23), see the Behavior Changes page for that version of the platform.

Continue by following the instructions in the next section.

Migrate to Android 7 (API level 24)

The following considerations apply to apps targeting Android 7.0 and higher versions of the platform:

  • Doze and App Standby

    Design for behaviors described in Optimizing for Doze and App Standby, which encompasses incremental changes introduced across several platform releases.

    When a device is in Doze and App Standby Mode, the system behaves as follows:

    • Restricts network access
    • Defers alarms, syncs, and jobs
    • Restricts GPS and Wi-Fi scans
    • Restricts normal-priority Firebase Cloud Messaging messages.
  • Permission Changes

    • The system restricts access to app private directories.
    • Exposing a file:// URI outside of your app triggers a FileUriExposedException. If you need to share files outside of your app, implement FileProvider
  • The system forbids linking to non-NDK libraries.

For an exhaustive list of changes introduced in Android 7.0 (API level 24), see the Behavior Changes page for that version of the platform.

Continue by following the instructions in the next section.

Migrate to Android 8 (API level 26)

The following considerations apply to apps targeting Android 8.0 and higher versions of the platform:

For an exhaustive list of changes introduced in Android 8.0 (API level 26), see the Behavior Changes page for that version of the platform.

Migrating from Android 8 (API 26) to Android 9 (API 28)

For an exhaustive list of changes introduced in Android 9.0 (API level 28), see behavior changes.

Migrating from Android 9 (API level 28) to Android 10 (API level 29)

Migrating from Android 10 (API level 29) to Android 11 (API level 30)

For an exhaustive list of changes introduced in Android 11 (API level 30), see the Behavior Changes page.

Continue to update to API 31 by following the instructions in the previous section.

Modernizing your apps

As you update the target API level for your apps, consider adopting recent platform features to modernize your apps and delight your users.

Check and update your SDKs and libraries

Make sure that your third-party SDK dependencies support API 31: Some SDK providers publish it in their manifest; others will require additional investigation. If you use an SDK that doesn't support API 31, make it a priority to work with the SDK provider to resolve the issue.

Additionally, note that your app or game's targetSdkVersion may restrict access to private Android platform libraries; see NDK Apps Linking to Platform Libraries for details.

You should also verify any restrictions that may exist in the version of the Android Support Library that you're using. As always, you must ensure compatibility between the major version of Android Support Library and your app’s compileSdkVersion.

We recommend that you choose a targetSdkVersion smaller than or equal to the Support Library’s major version. We encourage you to update to a recent compatible Support Library in order to take advantage of the latest compatibility features and bug fixes.

Test your app

After you update your app's API level and features as appropriate, you should test some core use cases. The following suggestions are not exhaustive, but aim to guide your testing process. We suggest testing:

  • That your app compiles to API 29 without errors or warnings.
  • That your app has a strategy for cases where the user rejects permission requests, and prompts the user for permissions. To do so:
    • Go to your app's App Info screen, and disable each permission.
    • Open the app and ensure no crashes.
    • Perform core use case tests and ensure required permissions are re-prompted.

  • Handles Doze with expected results and no errors.
    • Using adb, place your test device into Doze while your app is running.
      • Test any use cases that trigger Firebase Cloud Messaging messages.
      • Test any use cases that use Alarms or Jobs.
      • Eliminate any dependencies on background services.
    • Set your app into App Standby
      • Test any use cases that trigger Firebase Cloud Messaging messages.
      • Test any use cases that use Alarms.

  • Handles new photos / video being taken
  • Handles sharing files to other apps
    • Test any use case that shares file data with any other app (even another app by the same developer)
    • Test the content is visible in the other app and doesn’t trigger crashes.

Further information

Opt in to emails in the Google Play Console so that we can send you important updates and announcements from Android and Google Play, including our monthly partner newsletter.