감성개발자의 Blog

Article

Flutter Android API 레벨 업데이트

도입

flutter 이미지

flutter 이미지

Google은 Android 앱 생태계의 보안성과 최신성을 유지하기 위해 정기적으로 Android API 레벨의 최소 요구사항을 높입니다. Flutter 앱을 Google Play Store에 배포하거나 업데이트할 때 이 요구사항을 충족하지 않으면 배포가 거부됩니다. 이 글은 Flutter 프로젝트에서 이러한 요구사항에 대응하여 Android API 레벨을 업데이트하는 방법을 설명합니다.

문제 상황

Google Play Store에서 다음과 같은 경고나 거부 메시지를 받게 됩니다:

앱이 Android 14(API 수준 34) 이상을 타겟팅해야 합니다.

또는

Your app is targeting an older API level. Please update to target the latest Android API level.

이는 build.gradle 파일의 targetSdkVersion이 Google의 요구사항보다 낮다는 의미입니다.

해결 방법

1단계: build.gradle 파일 위치 파악

Flutter 프로젝트의 Android 설정은 다음 위치에 있습니다:

android/app/build.gradle

이 파일을 텍스트 에디터로 엽니다.

2단계: 현재 설정 확인

파일에서 다음 부분을 찾습니다:

android {
    compileSdkVersion xxx
    targetSdkVersion xxx
    // 다른 설정들...
}

또는 더 최신 형식:

android {
    compileSdkVersion = xx
    targetSdkVersion = xx
}

수정 방법 - 방식 1: 직접 수정

가장 직관적인 방식은 버전 번호를 직접 수정하는 것입니다:

android {
    compileSdkVersion 34
    targetSdkVersion 34
}

또는

android {
    compileSdkVersion = 34
    targetSdkVersion = 34
}

장점:

  • 명시적이고 직관적
  • IDE의 자동완성 지원
  • 특정 버전만 필요할 때 유연함

단점:

  • 팀원과 수동 업데이트 조율 필요

수정 방법 - 방식 2: Flutter 상수 사용

일부 Flutter 프로젝트는 다음과 같이 Flutter SDK의 설정을 참조하는 방식을 사용합니다:

android {
    compileSdkVersion flutter.compileSdkVersion
    targetSdkVersion flutter.targetSdkVersion
}

이 경우 Flutter SDK 자체의 설정을 변경해야 합니다:

표준 Flutter 설치

$FLUTTER_HOME/packages/flutter_tools/gradle/src/main/groovy

FVM(Flutter Version Manager) 사용 시

~/fvm/versions/stable/packages/flutter_tools/gradle/src/main/groovy

해당 디렉토리의 설정 파일을 찾아 compileSdkVersion과 targetSdkVersion을 원하는 버전으로 변경합니다.

장점:

  • Flutter 업그레이드 시 자동으로 권장 버전으로 변경
  • 팀 전체가 일관된 버전 사용

단점:

  • Flutter SDK 내부 설정 수정이므로 복잡함
  • IDE에서 추적이 어려울 수 있음

권장 사항

대부분의 경우

flutter upgrade

를 실행하면 자동으로 권장 버전으로 업데이트됩니다. 하지만 타이밍 문제로 수동 조정이 필요할 수 있습니다.

최신 권장 버전

현재(2024년 기준) Google Play Store의 요구사항:

  • targetSdkVersion: 34 이상 (Android 14)
  • compileSdkVersion: 34 이상

향후 요구사항이 변경될 수 있으므로 Google Play Console에서 주기적으로 확인하세요.

수정 후 확인

변경 사항 검증

cd android
./gradlew -q dependencies

또는

flutter pub get
flutter build apk

를 실행하여 빌드가 성공하는지 확인합니다.

앱 배포

flutter build appbundle

로 App Bundle을 빌드한 후 Google Play Console에 업로드합니다.

주의사항

  1. 호환성 확인: 앱의 의존성(라이브러리)가 새 API 레벨을 지원하는지 확인하세요. 오래된 라이브러리는 최신 API와 호환되지 않을 수 있습니다.

  2. 테스트 필요: 변경 후 반드시 Android 에뮬레이터나 실제 기기에서 테스트하세요.

  3. 점진적 업그레이드: 여러 단계를 거쳐 업그레이드하는 것이 안전합니다. 예를 들어 33 → 34로 한 단계씩 진행하세요.

  4. 문서화: 팀과 함께 작업한다면 변경 사항을 문서화하고 공유하세요.

마치며

Android API 레벨 업데이트는 복잡하지 않지만 중요한 유지보수 작업입니다. Google Play Store의 요구사항 변경을 주시하고 정기적으로 업데이트하는 것이 좋은 습관입니다. Flutter의 flutter upgrade 명령어도 유용하지만, 특정 상황에서는 수동 조정이 필요할 수 있습니다. 이 가이드를 참고하여 안전하게 업데이트하면 Google Play Store 배포 요구사항을 항상 충족할 수 있습니다.

댓글