minSdkVersion: 정의 및 최소 Android 버전 선택 방법

Android에서 minSdkVersion이란?

minSdkVersion은 build.gradle의 정수 매개변수로, 앱 설치를 위한 최소 Android API Level을 지정합니다. 기기의 API Level이 지정된 값보다 낮으면 PackageManager가 설치를 차단하고 Google Play Store는 해당 기기의 검색 결과에서 앱을 숨깁니다. minSdkVersion은 빌드 시 <uses-sdk android:minSdkVersion> 태그를 통해 AndroidManifest.xml에 기록되며 모든 설치 시 확인됩니다.

minSdkVersion 값은 사용자 도달 범위와 새 API 접근성 간의 균형입니다. minSdk가 낮을수록, 특히 오래된 Android 스마트폰이 인기 있는 개발도상국에서 더 많은 기기가 앱을 설치할 수 있습니다. minSdk가 높을수록 필요한 하위 호환성 코드가 줄어들고 런타임 검사 없이 더 많은 최신 API를 사용할 수 있습니다. Android Jetpack 및 AndroidX 라이브러리는 많은 새 API의 백포트를 이전 Android 버전에 제공하여 기능 손실 없이 낮은 minSdk를 선택할 수 있게 합니다.

minSdkVersion은 개발의 모든 단계에 영향을 미칩니다: 정적 분석(lint는 경고에 minSdk 사용), 종속성 호환성(라이브러리가 자체 minSdk를 필요로 할 수 있음), 테스트(minSdk가 있는 기기에서 테스트 필요), Google Play Console(사용자 도달 범위는 minSdk를 기반으로 계산됨). minSdkVersion 변경은 프로젝트 설정에서 가장 중요한 결정 중 하나이며, 코드, 테스트 및 사용자 기반에 영향을 줍니다.

minSdkVersion 지정 위치

Build.gradle.kts(Kotlin DSL)는 Android 프로젝트의 현대적 표준입니다. minSdk 매개변수는 모듈 수준의 defaultConfig 블록에서 설정됩니다. 값은 다양한 빌드 유형 및 제품 flavor에 대해 재정의될 수 있어, 기본 값을 변경하지 않고 낮은 API에서 테스트할 수 있습니다.

// build.gradle.kts — minSdk 기본 구성
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26      // Android 8.0 Oreo
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }

    // 다양한 flavor에 대한 minSdk 재정의
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

예제에서 minSdk = 26은 Android 8.0 Oreo에 해당합니다. 이는 2026년에 널리 사용되는 값입니다: Android Studio Distribution Dashboard에 따르면 기기의 ~15%만 제외합니다. compileSdk = 36은 모든 Android 16 API에 대한 액세스를 제공하고, targetSdk = 36은 최신 버전의 동작 변경 사항을 포함합니다. 디버그 빌드의 경우 이전 에뮬레이터에서 테스트하기 위해 minSdk를 낮출 수 있습니다.

minSdkVersion 선택 방법: 요소 및 전략

minSdkVersion 선택은 대상 사용자, API 요구 사항 및 라이브러리 생태계 분석에 기반한 전략적 결정입니다. 모든 프로젝트에 단일 올바른 값은 없습니다. 2026년에 Android Studio는 새 프로젝트의 기준선으로 minSdk = 26(Android 8.0)을 권장하지만, B2B 애플리케이션이나 엔터프라이즈 솔루션의 경우 더 낮거나 높은 값이 허용될 수 있습니다.

minSdkVersion 선택 요소

첫 번째 요소는 Distribution Dashboard입니다. Android Studio는 Google Play 데이터를 기반으로 API Level별 활성 기기 통계를 제공하며, 매월 업데이트됩니다. minSdkVersion은 대상 시장의 활성 기기 중 최소 90-95%를 커버해야 합니다. 아프리카 및 동남아시아에 사용자가 있는 국제 앱의 경우, 오래된 기기의 높은 비율로 인해 minSdk를 21(Android 5.0)로 낮춰야 합니다.

두 번째 요소는 종속성 요구 사항입니다. 각 라이브러리에는 매니페스트에 지정된 자체 minSdkVersion이 있습니다. 라이브러리가 minSdk 29를 필요로 하고 앱이 minSdk 26을 필요로 하는 경우, 매니페스트 병합 오류로 빌드가 실패합니다. 최신 Google Play Services 라이브러리는 minSdk 21, Firebase는 minSdk 21, 대부분의 Jetpack 라이브러리는 minSdk 21 또는 26, Compose BOM은 minSdk 21입니다. Compose의 경우 최소 임계값은 API 21입니다.

세 번째 요소는 필요한 API입니다. 앱의 핵심 기능이 특정 수준에서만 사용 가능한 API를 필요로 하는 경우(예: PhotoPicker — API 34, Predicted Navigation — API 35), 이는 minSdk를 높이는 것을 정당화할 수 있습니다. 그러나 낮은 minSdk를 유지하기 위해 AndroidX 백포트(Activity Result API, NotificationCompat)와 런타임 검사의 조합이 더 자주 사용됩니다.

단계별 선택 전략

1단계: Android Studio를 열고 File → New Project로 이동하여 마법사에서 권장 minSdk를 확인합니다. 2단계: Android Studio의 Distribution Dashboard를 확인합니다(View → Tool Windows → App Inspection → Distribution Dashboard). 3단계: 프로젝트 종속성을 분석합니다 — 빌드를 실행하고 매니페스트 병합 충돌을 수정합니다. 4단계: 백포트 없이 실제로 사용되는 API Level X를 평가합니다. 5단계: 대상 사용자의 90%+를 커버하고 모든 종속성과 호환되는 최소값으로 minSdk를 설정합니다.

기기 범위: API Level 분포 (2026년)

API Level별 기기 분포는 분기마다 변경되는 동적 지표입니다. 2026년 6월 기준 Android Studio Distribution Dashboard에 따르면, 활성 Android 기기의 약 85%가 API 26(Android 8.0) 이상, 72%가 API 29(Android 10) 이상, 55%가 API 31(Android 12) 이상에서 실행됩니다. 중국 시장은 많은 Huawei 기기에 Google Play Services가 없어 자체 통계를 가지고 있습니다.

GMS 기기(Google Mobile Services)는 더 빠르게 업데이트됩니다: 제조업체에 대한 Google Play의 의무 요구 사항 덕분에 API 31+ 비율이 68%에 도달합니다. 비GMS 기기(Huawei, Honor, 일부 중국 브랜드)는 더 오래된 분포를 가지고 있습니다: API 31+ 비율은 약 35%입니다. 앱이 국제 시장을 대상으로 하는 경우 글로벌 통계에 의존하십시오. 중국을 대상으로 하는 경우 비GMS 세그먼트를 고려하십시오.

결론: 국제 앱의 경우 minSdk 26이 최소 하위 호환성 비용으로 85%의 기기를 커버합니다. 개발도상국에 사용자가 있는 앱의 경우 minSdk 21(97% 커버리지)이 정당화되지만 레거시 API 작업에 더 많은 코드가 필요합니다. 제어된 기기 fleet을 가진 엔터프라이즈 앱의 경우 minSdk 31을 설정하고 폴백 코드를 완전히 제거할 수 있습니다.

하위 호환성: AndroidX, lint 및 @RequiresApi

하위 호환성은 낮은 minSdkVersion의 주요 과제입니다. AndroidX(이전 Support Library)는 최신 API의 백포트를 이전 Android 버전에 제공합니다: Material Design을 위한 AppCompatActivity, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat 등 수십 개의 구성 요소. 네이티브 API 대신 AndroidX 등가물을 사용하는 것이 호환성을 위한 첫 번째 단계입니다.

lint(Android Studio의 정적 분석기)는 minSdkVersion보다 높은 API 호출을 위해 코드를 스캔합니다. 메서드가 minSdk보다 높은 API Level에서 @RequiresApi로 주석 처리되고 검사 없이 호출되면 lint가 오류를 강조 표시합니다. 경고를 억제하려면 메서드에 @SuppressLint("NewApi") 주석을 사용하거나 전체 함수에 @RequiresApi(Build.VERSION_CODES.TIRAMISU)를 사용하십시오. 런타임 검사(Build.VERSION.SDK_INT를 통한)는 이전 기기에서 새 API를 안전하게 호출하는 주요 메커니즘입니다.

// 하위 호환성 예제: PhotoPicker (API 34+) 및 폴백
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — 모든 API Level에서 작동
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker는 API 34부터만 사용 가능
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // PhotoPicker 사용 (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // 폴백: GetContent (모든 버전에서 작동)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // 이 메서드는 API에서 호출할 수 없습니다 < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

ImagePickerActivity 클래스는 세 가지 수준의 하위 호환성을 보여줍니다. AndroidX의 Activity Result API는 모든 API Level에서 작동하므로 기본 이미지 선택은 minSdk에 의존하지 않습니다. PhotoPicker(ACTION_PICK_IMAGES)는 API 34부터만 사용 가능하며 GetContent로의 폴백과 함께 SDK_INT 검사 하에 호출됩니다. usePhotoPickerOnly 메서드는 @RequiresApi로 표시됩니다 — lint는 검사 없이 호출을 허용하지 않습니다. AndroidX의 AppCompat은 테마, 프래그먼트 및 애니메이션을 OS 버전에 자동으로 적용합니다.

라이브러리 및 모듈의 minSdkVersion

라이브러리(AAR, JAR)에도 매니페스트에 지정된 minSdkVersion이 있습니다. 라이브러리를 연결할 때 Gradle은 호환성을 확인합니다: 라이브러리의 minSdk가 앱의 minSdk보다 높으면 빌드가 오류로 실패합니다. 공개 라이브러리의 경우 소비자를 제한하지 않도록 가능한 가장 낮은 minSdk(대부분의 경우 21)를 지정하는 것이 좋습니다. 라이브러리가 API 29+를 필요로 하는 경우 잠재적 사용자의 ~28%를 잃습니다.

멀티 모듈 프로젝트는 모듈마다 다른 minSdkVersion 값을 가질 수 있습니다. 예를 들어 :core:network 모듈은 minSdk 26을, :feature:camera 모듈은 minSdk 29(특정 요구 사항이 있는 CameraX로 인해)를 가질 수 있습니다. Google Play는 기본 :app 모듈의 minSdk가 모든 종속 모듈의 minSdk보다 낮거나 같아야 한다고 요구합니다. 실제로 동일한 앱의 모든 모듈은 유지 관리를 쉽게 하기 위해 일반적으로 동일한 minSdk를 가집니다.

// build.gradle.kts — 낮은 minSdk의 라이브러리 모듈
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // 최대 커버리지를 위한 최소
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, 백포트 추가
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

minSdk = 21인 라이브러리 모듈은 97%의 기기와 호환되며 소비자를 제한하지 않습니다. 라이브러리가 21보다 높은 API를 사용하는 경우 개발자는 런타임 검사를 추가하거나 관련 메서드에 @RequiresApi를 지정해야 합니다. AndroidX Core KTX(minSdk 21)는 Context, Bundle, Locale 및 기타 시스템 클래스에 대한 백포트를 제공하여 라이브러리가 낮은 minSdk를 유지할 수 있게 합니다.

minSdkVersion 선택 시 일반적인 실수

minSdk 선택 시 실수는 수천 번의 설치 또는 몇 주간의 추가 개발 비용이 들 수 있습니다. 첫 번째 일반적인 실수는 Distribution Dashboard를 분석하지 않고 프로젝트 템플릿에서 minSdk를 복사하는 것입니다. 많은 개발자가 Android Studio 템플릿에서 minSdk = 21을 그대로 두지만, minSdk 26이 사용자에게 충분하고 코드 내 SDK_INT 검사 수를 줄일 수 있습니다.

두 번째 실수는 시장을 고려하지 않고 너무 높은 minSdk를 설정하는 것입니다. 국제 앱에 minSdk = 31(Android 12)을 설정하면 ~45%의 기기를 잃게 됩니다. 스타트업이나 대규모 사용자 기반 앱의 경우 이는 재앙입니다. minSdk를 높이기 전에 항상 Distribution Dashboard를 확인하고 확실하지 않은 경우 Google Play Console에서 A/B 테스트를 사용하십시오.

세 번째 실수는 종속성 minSdk 무시입니다. 새 라이브러리를 추가할 때 문서나 POM 파일에서 해당 minSdk를 확인하십시오. Firebase ML Kit는 minSdk 21을 필요로 하고, 일부 사용자 정의 카메라 라이브러리는 minSdk 29를 필요로 합니다. 새 라이브러리로 인해 프로덕션에서 매니페스트 병합이 실패하면 수정하는 데 며칠이 걸릴 수 있습니다.

// 예제: 런타임 API 호환성 검사
fun checkFeatureAvailability(): Boolean {
    // 일반적인 실수 — SDK_INT 검사 없이 API 호출
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — PhotoPicker 사용
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — MediaStore 사용
            true
        }
        else -> {
            // API < 29 — ACTION_GET_CONTENT 사용
            true
        }
    }
}

API Level 검사의 올바른 아키텍처는 minSdk에서 compileSdk까지 가능한 모든 값을 커버하는 범위가 있는 when 표현식입니다. 핵심 규칙: Level X의 API 호출은 minSdk에서 X까지의 API Level을 가진 모든 기기에 대해 VERSION.SDK_INT 검사로 보호되어야 합니다. lint는 검사되지 않은 호출을 감지하는 데 도움이 되지만 동적 코드에 대한 완전한 커버리지를 보장할 수는 없습니다.