How to Adjust Android minSdkVersion in Flutter Projects: In-depth Analysis and Best Practices

Problem Background and Error Analysis

During Flutter development, developers often encounter minSdkVersion conflicts when integrating certain dependency libraries. A typical error message appears as follows:

FAILURE: Build failed with an exception.

  * What went wrong:
  Execution failed for task ':app:processDebugManifest'.
  > Manifest merger failed : uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:flutter_blue] /home/maldus/Projects/flutter/polmac/build/flutter_blue/intermediates/manifests/full/debug/AndroidManifest.xml as the library might be using APIs not available in 16
    Suggestion: use a compatible library with a minSdk of at most 16,
            or increase this project's minSdk version to at least 19,
            or use tools:overrideLibrary="com.pauldemarco.flutterblue" to force usage (may lead to runtime failures)

This error indicates that the current project's minSdkVersion is set to 16, while the flutter_blue library requires a minimum SDK version of 19. This version mismatch causes build failures because the library may use APIs unavailable in lower Android versions.

Solution 1: Direct Modification of build.gradle File

The most straightforward approach involves modifying the minSdkVersion configuration in the project's android/app/build.gradle file. Here are the specific modification steps:

android {
    defaultConfig {
        applicationId "com.example.projectname"
        minSdkVersion 19
        targetSdkVersion 28
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    }
}

In this configuration, change minSdkVersion from the default 16 to 19 (or higher) to ensure compatibility with dependency library requirements. After modification, rebuild the project to apply the changes.

Solution 2: Configuration via local.properties (Flutter 2.8+)

For Flutter 2.8 and later projects, a more flexible configuration approach is recommended. First, add minSdkVersion configuration in the android/local.properties file:

sdk.dir=C:\\Users\\ms471\\AppData\\Local\\Android\\sdk
flutter.sdk=C:\\src\\flutter
flutter.buildMode=debug
flutter.versionName=1.0.0
flutter.versionCode=1
flutter.minSdkVersion=23

Then reference this configuration in the android/app/build.gradle file:

android {
    compileSdkVersion localProperties.getProperty('flutter.compileSdkVersion').toInteger()
    
    defaultConfig {
        minSdkVersion localProperties.getProperty('flutter.minSdkVersion').toInteger()
        targetSdkVersion localProperties.getProperty('flutter.targetSdkVersion').toInteger()
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
}

This method offers the advantage of centralized configuration management, ensuring consistency across different environments.

Solution 3: Global Modification of Flutter SDK Defaults

For developers needing to set a unified minSdkVersion for all new projects, global modification of Flutter SDK configuration is available. Before Flutter 3.13, edit the flutter/packages/flutter_tools/gradle/flutter.gradle file:

class FlutterExtension {
    static int compileSdkVersion = 31
    static int minSdkVersion = 20
    static int targetSdkVersion = 31
}

Starting from Flutter 3.13, the configuration file location changes to flutter/packages/flutter_tools/gradle/src/main/groovy/flutter.groovy. Note that Google Play Store currently requires apps to have a minimum SDK version of 20 or higher, so setting minSdkVersion to 20 or above is recommended to ensure compliance with store publication requirements.

Version Compatibility Considerations

When selecting minSdkVersion, balance functional requirements with user coverage. Higher minSdkVersion values provide access to more modern APIs but exclude users with older Android versions. According to statistical data, user coverage for Android 5.0 (API 21) and above exceeds 95%, making minSdkVersion 21 or higher a relatively safe choice.

Best Practice Recommendations

In practical development, follow these best practices: First, check minSdkVersion requirements for all project dependencies and select the highest version that satisfies all requirements. Second, consider the device distribution of your target user base. Finally, regularly update minSdkVersion to leverage new API features and ensure application security. For new projects, starting directly from minSdkVersion 21 is recommended to avoid many compatibility issues and fully utilize modern Android system features.