Flutter 안드로이드 타겟 SDK 대응하기 (targetSdkVersion 경고)

평화로운 개발 인생에 또 구글이 정기적으로 시련을 준다. "앱이 Android 14(API 수준 34) 이상을 타겟팅해야 함"이라는 경고 메일이다.

구글 플레이는 매년 새 앱과 업데이트에 대해 타겟 API 레벨 최소 요구치를 올린다. 대응하지 않으면 업데이트 자체를 올릴 수 없다.

기본적으로 손봐야 할 코드

수정할 위치는 android/app/build.gradle 이다.

compileSdkVersion : xxx
targetSdkVersion  : xxx

Android 14 대응이라면 이렇게 변경되어야 한다.

compileSdkVersion : 34
targetSdkVersion  : 34

두 가지 선택지

여기서 우리는 2가지 선택을 해야 한다.

• 1. build.gradle 파일을 직접 수정할 것인가?
• 2. 거기에 박혀 있는 flutter 상수를 수정할 것인가?

Flutter 프로젝트는 기본적으로 compileSdkVersion이 flutter.compileSdkVersion 같은 상수로 되어 있다.

전자: 직접 입력

android {
    compileSdkVersion 34
    
    defaultConfig {
        targetSdkVersion 34
        minSdkVersion 21
    }
}

해당 프로젝트에만 적용된다. 명시적이라 다른 사람이 봐도 바로 알 수 있다는 게 장점이다.

후자: Flutter 상수 변경

flutter SDK가 설치되어 있는 위치에서 아래 경로로 이동한다.

packages/flutter_tools/gradle/src/main/groovy

# fvm으로 버전 관리 중이라면
~/fvm/versions/stable/packages/flutter_tools/gradle/src/main/groovy

거기서 flutter.groovy 의 값을 원하는 대로 변경하면, 이후 만드는 모든 프로젝트에 기본값으로 적용된다. 프로젝트마다 하드코딩하는 게 귀찮다면 이 방법이 편하다.

다만 단점이 명확하다.

• flutter upgrade 하면 초기화된다. SDK 파일을 직접 고치는 것이라 업그레이드 시 덮어씌워진다
• 팀원과 값이 달라진다. 내 로컬에서는 되는데 CI나 다른 사람 환경에서는 안 되는 상황이 생긴다
• Git에 남지 않는다. 왜 이 값인지 추적이 안 된다

그래서 팀 프로젝트라면 프로젝트 파일에 직접 명시하는 쪽을 권한다.

참고로 보통은 flutter upgrade를 하면 알아서 바뀐다. Flutter 팀이 SDK 버전을 따라 올려주기 때문에, 최신 Flutter로 올리는 것만으로 해결되는 경우가 많다.

버전을 올린 뒤에 확인할 것들

숫자만 바꾼다고 끝이 아니다. 타겟 SDK를 올리면 동작 변경 사항이 적용된다. 이게 진짜 작업이다.

Android 13 (API 33)

• 알림 권한이 런타임 권한으로 바뀜 — POST_NOTIFICATIONS 를 직접 요청해야 한다. 안 하면 푸시가 아예 안 온다
• 미디어 접근 권한 세분화 — READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_AUDIO

Android 14 (API 34)

• 포그라운드 서비스 타입 선언 필수 — foregroundServiceType 을 매니페스트에 명시해야 한다
• 암시적 인텐트 제한 — 내보내지 않은 컴포넌트에 암시적 인텐트를 보낼 수 없다
• BroadcastReceiver 등록 시 export 여부 명시 필수

공통으로 확인할 것

• 플러그인 호환성 — 사용 중인 패키지가 새 SDK를 지원하는지. flutter pub outdated 로 확인
• Gradle / AGP 버전 — compileSdk를 올리면 Android Gradle Plugin과 Gradle 버전도 함께 올려야 하는 경우가 많다
• Java 버전 — AGP 8부터 Java 17이 필요하다
• 실기기 테스트 — 에뮬레이터에서는 안 잡히는 권한 이슈가 실기기에서 나온다

작업 순서 권장

• 1. flutter upgrade 로 SDK를 먼저 올린다
• 2. flutter pub outdated 로 패키지 상태 확인 후 업그레이드
• 3. build.gradle의 compileSdk / targetSdk 수정
• 4. 빌드해서 에러부터 잡는다 (Gradle, AGP, Java 버전)
• 5. 권한 관련 동작 변경 사항 대응
• 6. 실기기에서 알림·카메라·저장소 기능 테스트
• 7. 내부 테스트 트랙에 먼저 올려 확인

한 번에 다 하려고 하면 어디서 깨졌는지 모르게 된다. 빌드가 되는 지점까지 먼저 만들고, 그다음에 동작 변경을 다루는 순서가 편하다.

정리

• android/app/build.gradle 의 compileSdkVersion, targetSdkVersion 수정
• Flutter SDK 상수를 고치는 방법도 있지만 flutter upgrade 시 초기화된다
• 팀 프로젝트는 프로젝트 파일에 직접 명시
• 보통은 flutter upgrade만으로 해결된다
• 숫자를 올리면 동작 변경 사항이 따라온다. 알림 권한(13), 포그라운드 서비스 타입(14)
• 반드시 실기기에서 테스트