The HCWRM Release Gatekeeper: A Practical Checklist for Google Play's Target API Level & SDK Requirements

Every Android developer remembers a moment when a seemingly routine release got blocked by a policy violation. The target API level requirement from Google Play is one of the most common—and most avoidable—rejection reasons. This guide from HCWRM.top gives you a repeatable checklist to verify compliance before you hit 'Submit.' We focus on the practical steps, not the theory.

By the end of this article, you'll be able to audit your app's targetSdkVersion, update SDK dependencies without breaking existing features, handle new permission models like granular media access, and set up a release pipeline that catches issues early. Let's start with why this matters and what happens when you ignore the deadline.

1. Who Needs This and What Goes Wrong Without It

If you distribute apps on Google Play, the target API level requirement applies to you—whether you're a solo developer or part of a large team. Every year, Google sets a deadline by which new apps and updates must target a specific Android API level (the latest is typically the current year's release plus one year). Missing that deadline means your app cannot be published or updated until you comply.

But the pain isn't just about the deadline. Many teams unknowingly fail compliance because of subtler issues: a third-party SDK that still targets an older API level, a misconfigured build.gradle file, or a dependency that uses deprecated permissions. For example, one team I read about was blocked because their analytics SDK hadn't been updated to support scoped storage, and the app crashed on Android 11 devices when trying to access media files. They had to roll back the release, update the SDK, and resubmit—losing two weeks of launch momentum.

Common failure modes

The most frequent problems we see fall into three categories. First, the app's targetSdkVersion is set correctly, but some library or module within the project still references an older version. Second, the app targets the correct API level but uses permissions or APIs that are restricted or deprecated in that level—like requesting READ_EXTERNAL_STORAGE without proper justification. Third, the app passes Google Play's automated checks but fails on actual devices because of behavioral changes introduced in the new API level (e.g., background location limits or foreground service restrictions).

Who is most at risk

Teams managing multiple apps or legacy projects are especially vulnerable. If you have an app that hasn't been updated in over a year, the gap between its current target API level and the required one can be several versions. Upgrading across multiple API levels introduces breaking changes that need careful testing. Similarly, apps that rely heavily on community-maintained libraries or deprecated SDKs often find themselves stuck when those dependencies don't keep up with Google's timeline.

Another group that struggles is teams without a dedicated CI/CD pipeline. Without automated checks, it's easy to forget to update the targetSdkVersion in a branch that's been sitting for weeks. A manual checklist helps, but it's not foolproof. That's why we've designed this guide to work both for manual audits and for integration into automated release scripts.

2. Prerequisites and Context You Should Settle First

Before you run through the checklist, there are a few things you need to have in place. First, make sure you have access to the Google Play Console with the right permissions (Owner or Admin role for the app you're checking). You'll also need a development environment where you can build and test the app—Android Studio with the latest SDK tools installed.

Understand the current deadline

As of early 2025, Google requires new apps to target API level 34 (Android 14) and updates to target at least API level 33 (Android 13). These deadlines shift every year, so always check the official Google Play Console policy page for the most current requirements. A common mistake is to assume that last year's level is still acceptable—it almost never is after the grace period ends.

Know your app's dependencies

You need a complete list of all SDKs and libraries your app uses, including their current target API levels. Tools like Gradle's dependency tree (./gradlew app:dependencies) can show you the full graph. Pay special attention to SDKs that manage ads, analytics, push notifications, and location services—these are the most likely to lag behind in updates.

Set up testing on target devices

You cannot rely solely on emulators or automated tests for behavioral changes. The new API level may introduce runtime permission changes, background execution limits, or battery optimizations that only appear on real hardware. Ideally, test on at least one device running the minimum required API level (e.g., Android 13 or 14) and one running a newer version to check forward compatibility.

Backup your current build

Before making any changes, ensure you have a tagged version of your working codebase. If something breaks during the upgrade, you need to be able to roll back quickly. This is especially important if you're working under a tight release deadline.

3. Core Workflow: Step-by-Step Compliance Checklist

Here is the exact sequence we recommend for verifying and achieving target API level compliance. Follow these steps in order for the most reliable results.

Step 1: Audit your current targetSdkVersion

Open your app-level build.gradle file (or build.gradle.kts for Kotlin DSL). Look for the line that sets targetSdkVersion. If you're using the new Gradle 8.x plugin, it may be set via the android.defaultConfig block. Write down the current value. Also check compileSdkVersion—it should be at least as high as your target. If compileSdkVersion is lower, update it first.

Step 2: Check each dependency's target level

Run ./gradlew app:dependencies to see all transitive dependencies. For each library, note its declared targetSdkVersion. You can often find this by looking at the library's AAR manifest or its documentation. If any library targets an API level lower than your required one, you have two options: update the library to a newer version that supports the required level, or if no update exists, contact the library maintainer or consider replacing it.

Step 3: Update targetSdkVersion and compileSdkVersion

Change the targetSdkVersion in your build.gradle to the required level (e.g., 33 or 34). Also update compileSdkVersion to match or exceed it. Sync your project and let Gradle download any new platform SDKs if needed.

Step 4: Address behavioral changes

Each new API level introduces changes that can break existing functionality. For example, Android 13 (API 33) introduced granular media permissions (READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_AUDIO) instead of the old READ_EXTERNAL_STORAGE. You must update your permission requests and manifest declarations accordingly. Check the official Android developer documentation for a migration guide for your target level.

Step 5: Test thoroughly

Build and install the app on a device or emulator running the target API level. Run through all core flows, especially those that involve permissions, background work, or file access. Pay extra attention to features that use deprecated APIs—they may still compile but throw runtime exceptions on newer OS versions.

Step 6: Submit to internal testing track

Upload your APK or App Bundle to Google Play Console's internal testing track. This triggers the same automated policy checks that the production track uses, but you can catch issues before they block a wider release. If the internal test passes, you're ready for production. If it fails, Google Play Console will show a specific violation message—use that to debug.

4. Tools, Setup, and Environment Realities

Getting the right tools in place can save hours of manual work. Here are the essential tools and how to set them up for compliance checking.

Android Studio and SDK Manager

Ensure you have the latest stable version of Android Studio (at least Hedgehog or later). Use the SDK Manager to install the platform SDKs for the API levels you need to target. You can also install the 'Google Play Services' and 'Google Repository' packages to get the latest versions of Google's libraries.

Gradle wrapper and build tools

Update your Gradle wrapper to the latest supported version (check the Android Gradle Plugin compatibility table). An outdated build system can cause subtle issues with dependency resolution or manifest merging. Run ./gradlew wrapper --gradle-version=8.4 (or the current stable) to update.

Automated lint checks

Add a Gradle task to run lint checks that target API compatibility. In your build.gradle, you can configure lint to fail on errors related to 'NewApi' or 'Deprecated' usage. For example:

android {
  lintOptions {
    abortOnError true
    check 'NewApi', 'Deprecated'
  }
}

This will catch code that uses APIs not available in your minSdkVersion or that are deprecated in your targetSdkVersion.

CI/CD integration

If you use a CI system like GitHub Actions, Jenkins, or GitLab CI, add a step that runs the dependency audit and lint checks automatically. You can also use the Google Play Developer API to check the current required target API level programmatically, but that's more advanced. A simpler approach is to have a manual checklist that a team member runs before every release.

Third-party SDK update tools

Some teams use dependency management tools like Dependabot or Renovate to automatically create pull requests when a library updates. While these tools don't specifically check target API levels, they help keep your dependencies current, which reduces the risk of compliance failures.

5. Variations for Different Constraints

Not every app is the same. Here are common scenarios and how to adapt the checklist for each.

Legacy app with no recent updates

If your app was last updated two or more years ago, you're likely jumping multiple API levels (e.g., from 28 to 33). In this case, break the upgrade into phases: first update to the intermediate API levels one at a time, testing each step. For example, go from 28 to 30, then 30 to 33. This makes it easier to isolate breaking changes. You may also need to update dependencies that have since been deprecated.

App with proprietary or unmaintained SDKs

When a critical third-party SDK hasn't been updated to support the required target API level, you have limited options. Contact the vendor and ask for an ETA. If none exists, consider replacing the SDK with an alternative that is actively maintained. In the short term, you can sometimes work around the issue by excluding the library's manifest entries (using tools:node='replace' in your own manifest) or by overriding its targetSdkVersion via Gradle, but this is risky and not officially recommended.

Multiple apps managed by one team

If you maintain several apps, standardize your build configurations. Create a shared Gradle script (e.g., a convention plugin) that sets the targetSdkVersion and compileSdkVersion for all apps. This ensures consistency and makes it easier to update all apps at once. You can also create a shared CI pipeline that runs the compliance checks for every app.

App using Flutter or React Native

Cross-platform frameworks still require native Android configuration. In Flutter, the targetSdkVersion is set in the android/app/build.gradle file. In React Native, it's in the android/app/build.gradle as well. The same checklist applies, but you also need to ensure that any native modules you use are updated to support the target API level. Check the framework's documentation for any additional steps.

6. Pitfalls, Debugging, and What to Check When It Fails

Even with a solid checklist, things can go wrong. Here are the most common failure modes and how to fix them.

Google Play Console shows 'Target API level not met'

This usually means your APK or App Bundle's manifest declares a targetSdkVersion lower than required. Double-check your build.gradle and ensure you've rebuilt the app after changing the value. A common oversight is that a library's manifest overrides your targetSdkVersion—you can inspect the merged manifest in Android Studio under app/build/intermediates/merged_manifests/debug/. Look for the uses-sdk element and verify it shows the correct level.

App builds fine but crashes on newer devices

This often happens when you've updated the targetSdkVersion but haven't adjusted for behavioral changes. For example, if you target API 33 but still request the old READ_EXTERNAL_STORAGE permission, the system will grant it only if your app is already on the user's device before they upgrade to Android 13. New installs on Android 13 won't get that permission. Use the Android Compatibility Test Suite (CTS) or manual testing to catch these issues.

Dependency conflict causing build failure

When you update compileSdkVersion, some libraries may require a newer version of the Android Gradle Plugin or other dependencies. If you see build errors like 'Cannot resolve symbol' or 'Failed to transform', update your AGP version and all Google Play Services dependencies to their latest versions. Use the 'dependency check' tool in Android Studio to find conflicts.

Permission request rejected by policy

Even if your code is correct, Google Play may reject your app if it uses certain permissions without a valid reason (like SMS or call log permissions). Review the Permissions Declaration form in Google Play Console and ensure you've provided a justification. If you no longer need the permission, remove it from your manifest.

What to do when nothing seems to work

First, check the Google Play Console's 'Policy and Programs' section for any specific guidance. Sometimes the issue is not the target API level itself but another policy (like Data Safety or Ads ID compliance) that blocks the release. Second, search the official Android Developers issue tracker for known problems with the API level you're targeting. Third, consider using the 'Pre-launch report' feature in Play Console to get automated testing results—it often catches runtime crashes you missed.

If all else fails, you can contact Google Play support through the console. Be prepared to share your APK, the exact error message, and a list of steps you've already taken. They usually respond within a few business days.