Supporting Legacy Android Devices Without Freezing a Modern Codebase

Supporting Android 6 or 7 in a codebase that still needs modern tooling creates a misleading choice: either keep the old devices and stop upgrading, or modernize the app and abandon deployed hardware. In many enterprise fleets, neither option is acceptable.

The better approach is to treat legacy support as a compatibility boundary. Keep the build toolchain, target SDK, architecture, and most application code moving forward, while isolating the small set of APIs, dependencies, and behaviors that actually differ on older devices.

That distinction matters because minSdk and targetSdk solve different problems. Android uses minSdkVersion to decide the oldest platform on which the app can install, while targetSdkVersion communicates which platform behavior the app has been tested against. Raising the target SDK does not automatically require raising the minimum SDK.

Start with the real compatibility contract

Before changing code, write down the device floor as a product constraint rather than letting it emerge accidentally from Gradle errors.

For example:

Required fleet floor: Android 6.0 / API 23
Primary fleet: Android 7.0 / API 24 and newer
compileSdk: current supported SDK
 targetSdk: current release requirement
minSdk: 23

The exact values depend on your fleet, but the separation is the important part. Android’s <uses-sdk> documentation explicitly distinguishes the minimum API required to run from the API level the application targets.

This gives the team a stable question for every upgrade: does this change really require a newer runtime, or does it only require a newer compiler or target SDK?

Audit dependencies before application code

A modern application can contain perfectly guarded Kotlin code and still stop installing on an old device because one dependency raises its minimum SDK.

Treat dependency upgrades as compatibility changes. For each library update, check:

1. its declared minimum Android API;
2. whether it bundles native libraries for the device architecture;
3. whether a newer version removed an API or fallback your old devices depend on;
4. whether manifest merging silently raises the application’s effective minimum SDK.

This is especially important for hardware fleets where CPU architecture varies. If native .so files are involved, the Android ABI filters guide explains why architecture packaging should be treated as a compatibility decision rather than only an APK-size optimization.

A useful CI check is to build the production variant and inspect the merged manifest instead of trusting only the value written in your app module.

./gradlew :app:processReleaseMainManifest
./gradlew :app:assembleRelease

If an upgrade changes the effective device floor, fail the upgrade deliberately rather than discovering it during field installation.

Put newer APIs behind narrow boundaries

Do not scatter version checks across screens and ViewModels. Put them near the platform operation they protect.

interface DeviceCapability {
    fun supportsModernFeature(): Boolean
}

class AndroidDeviceCapability : DeviceCapability {
    override fun supportsModernFeature(): Boolean =
        Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
}

For behavior that needs different implementations, select the implementation once:

fun createPlatformAdapter(): PlatformAdapter =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        ModernPlatformAdapter()
    } else {
        LegacyPlatformAdapter()
    }

The goal is not to create a parallel legacy application. It is to keep version-specific code small enough that the rest of the codebase can remain ordinary modern Android code.

Treat permissions as a behavior matrix

Android 6.0 introduced runtime permissions for dangerous permissions. That means API 23 is not just an old visual environment. It is a behavioral boundary that still affects camera, location, storage, and other sensitive capabilities.

Android’s runtime permission guidance says dangerous permissions must be requested at runtime on Android 6.0 and higher. Newer Android releases add more permission behavior changes, so a single permission granted assumption is not a sufficient compatibility strategy.

Model permissions by capability:

fun canUseCamera(context: Context): Boolean {
    return ContextCompat.checkSelfPermission(
        context,
        Manifest.permission.CAMERA
    ) == PackageManager.PERMISSION_GRANTED
}

Then test the feature in denied, granted, and revoked states on the oldest supported API as well as on a current API. This keeps permission logic tied to what the feature needs instead of to a growing collection of OS-version conditionals.

Separate scheduling requirements from OS age

Background work is another place where teams often add legacy branches too quickly. First classify the requirement: does the task need guaranteed eventual execution, or must it happen at a precise wall-clock time?

For deferrable work, WorkManager is usually the right abstraction. For user-visible exact alarms, AlarmManager may be appropriate. The WorkManager vs AlarmManager decision guide covers that distinction in detail.

The compatibility lesson is broader: choose the semantic abstraction first, then add an OS-specific fallback only where the abstraction cannot cover the required behavior.

Build a small but intentional device matrix

Supporting old Android versions does not mean testing every API level on every commit. It means testing the boundaries where behavior changes.

A practical matrix can contain four lanes:

Lane	Purpose
Oldest supported API	Proves installation, startup, permissions, storage, networking, and core transactions
Most common fleet API	Represents the majority of deployed hardware
Current target API	Catches target-SDK behavior changes
Current Android release	Catches forward-compatibility problems early

Use emulators for broad regression coverage, but keep at least one representative physical device when hardware integrations, vendor firmware, cameras, printers, card readers, or low-memory behavior matter.

Android’s compatibility testing tools are useful when a target-SDK upgrade changes behavior. They let you isolate compatibility changes instead of debugging a large platform upgrade as one opaque failure.

Optimize for the weakest device without designing only for it

Legacy fleets often combine old Android versions with limited RAM and slower storage. That makes performance constraints easy to confuse with API compatibility.

Keep them separate. API guards solve unavailable platform behavior. Memory profiling, image sizing, cache limits, and process lifecycle handling solve resource pressure. The low-RAM Android optimization guide covers that second problem without turning the entire architecture into a legacy-only design.

This separation also makes retirement easier. When the last API 23 device leaves the fleet, you should be able to remove a compatibility adapter and raise minSdk, not untangle years of legacy assumptions from every feature.

Common failure modes

The first failure mode is freezing dependencies indefinitely. It feels safe, but it accumulates security, tooling, and maintenance debt while making the eventual migration larger.

The second is raising minSdk to fix a build error without proving that the application truly requires the newer runtime. Often the actual blocker is one dependency or one unguarded API call.

The third is testing only on the newest emulator. Compilation proves that code can be built against an SDK. It does not prove that the same artifact installs and behaves correctly on the minimum supported platform.

The fourth is creating a full legacy branch of the application. Unless the products genuinely diverge, long-lived branches duplicate fixes and make compatibility harder to reason about. Prefer narrow adapters, capability checks, and a shared test matrix.

A repeatable upgrade workflow

For each target SDK, AGP, Kotlin, or major dependency upgrade, use the same sequence:

1. keep the required minSdk fixed;
2. upgrade one major compatibility surface at a time;
3. inspect dependency and merged-manifest minimum SDK requirements;
4. compile and run lint checks for unavailable APIs;
5. run smoke tests on the oldest supported device;
6. exercise permissions, networking, storage, background work, and hardware integrations;
7. run the same critical path on the current target API;
8. record any fallback as an explicit compatibility adapter with a removal condition.

This turns legacy Android support from a vague fear into a finite engineering contract.

Keep modernization and compatibility independent

A device fleet can remain on Android 6 or 7 while the engineering practices around it improve. The codebase can adopt newer Kotlin, stronger CI, clearer architecture, better tests, and a current target SDK as long as runtime compatibility is verified deliberately.

The sustainable goal is not to make old devices behave like new ones. It is to know exactly which boundaries are old, keep those boundaries small, and let everything else continue to evolve.