How to Upgrade Android Target SDK from 28 to 31: Challenges, Solutions & Best Practices

Why Target SDK Matters

Android Target version serves as a protocol and bridge between an app and the system, influencing pre‑install cooperation, app‑store exposure, and open‑ability; higher targets improve security but introduce more constraints and hidden pitfalls, especially for complex, high‑stability super‑apps.

Gaode Map Case Study

Gaode Map upgraded from Target 28 to the latest Target 31, becoming the first major app to do so, meeting market and pre‑install compliance and gaining a time window for early market entry. The team documented the encountered problems, principles, solutions, and migration steps to help others upgrade efficiently.

1.1 Definition of Target Version

Target version signals that the app complies with the specified system version and is willing to be bound by its constraints. It offers a flexible, buffered adaptation path, allowing users to stay on an older target while preparing for the newer one.

1.2 Why the Upgrade Is Fast and Costly

Manufacturers are accelerating Target upgrades to tighten privacy and user‑experience requirements. Fragmented devices, varying OEM implementations, and frequent API changes increase adaptation cost, especially when documentation is incomplete.

1.3 Benefits of Upgrading

Meets app‑store and OEM pre‑install compliance, providing early‑market advantages.

Encapsulates compliance experience into a system isolation layer, reducing future impact.

Through source analysis and custom scripts, identified 13 undocumented changes, avoiding 119 potential crashes.

2.1 External & Scoped Storage (Target 29‑31)

Upgrading to Target 29 grants partitioned storage access: apps can only see their sandbox and specific media directories. Legacy external storage can be disabled via requestLegacyExternalStorage and PreserveLegacyExternalStorage, but new installations on Android 11+ force partitioned storage.

Pitfall: On Android 11+ with Target ≥30, writing beyond the second‑level /sdcard directory may still report writable but throws an exception on actual write.

Advice: Double‑check system write results; if writable, attempt a temporary file write to confirm.

2.2 Bluetooth Permissions Changes

Target ≤28 uses BLUETOOTH and BLUETOOTH_ADMIN; Target 29‑30 adds precise location requirement; Target ≥31 replaces them with fine‑grained permissions BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and BLUETOOTH_ADVERTISE. The article provides a permission matrix and a combined‑request strategy.

<!-- Request legacy Bluetooth permissions on older devices. -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

New permissions are declared as:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

2.3 Approximate (Coarse) Location (Target 31)

Android 12 separates precise and approximate location, allowing users to grant only approximate location. Apps that rely on precise location must adapt to request ACCESS_FINE_LOCATION and handle the case where only coarse location is granted.

2.4 Background Location (Target 29‑31)

Target 29 introduces ACCESS_BACKGROUND_LOCATION; it must be declared in the manifest and dynamically requested with user selection of “Always allow”. For Target ≥30 the same rule applies, and the system ignores direct runtime requests for this permission.

2.5 Exact Alarm Permission (Target 31)

Apps that need exact alarms must declare SCHEDULE_EXACT_ALARM and perform runtime checks, as the system can revoke this special access.

2.6 Package Visibility (Target 30‑31)

Android 11 requires a <queries> element to list visible packages, reducing the need for QUERY_ALL_PACKAGES, which is now restricted on Google Play.

2.7 WLAN Restrictions (Target 29‑31)

Access to Wi‑Fi scan results now requires precise location; saved networks are inaccessible without new APIs like addNetworkSuggestions. Apps must adapt to the new APIs and handle user confirmation dialogs.

3.1 Exported Attribute (Target 31)

Components with intent filters must explicitly declare android:exported; otherwise the app cannot be installed on Android 12+ devices.

3.2 Foreground Service Limits (Target 31)

Starting a foreground service from the background is prohibited except for exempted cases; developers should audit all startForegroundService calls.

3.3 Camera & Microphone in Foreground Services (Target 30‑31)

Foreground services that use camera or microphone must declare the corresponding foregroundServiceType (e.g., camera|microphone).

3.4 PendingIntent Mutability (Target 31)

All PendingIntent instances must specify FLAG_IMMUTABLE or FLAG_MUTABLE to improve security.

3.5 Non‑SDK Interface Restrictions (Target 29‑31)

Android restricts usage of non‑SDK APIs; developers should rely on whitelisted SDK APIs, use grey‑list APIs cautiously, and avoid black‑list APIs, wrapping calls with try‑catch.

Conclusion

The upgrade of Target SDK is driven by external policies, internal commitment to privacy compliance, and cross‑team collaboration. It requires systematic analysis, code isolation, and continuous adaptation to avoid crashes and maintain user trust.