SDK Platform: 정의, 버전 및 Android SDK Manager

SDK Platform이란

SDK Platform은 Android SDK의 기본 구성 요소로, 특정 Android 버전용 애플리케이션을 개발하기 위한 라이브러리 및 도구의 완전한 세트를 제공합니다. 각 플랫폼은 API Level(새 OS 릴리스와 함께 증가하는 정수)로 식별됩니다. 예를 들어, Android 13은 API Level 33, Android 14는 API Level 34, Android 15는 API Level 35에 해당합니다.

Android Studio(IDE)와 달리 SDK Platform에는 코드 편집기나 디버거가 포함되어 있지 않습니다. 컴파일러 및 빌드 시스템에 연결되는 시스템 계층입니다. 개발자가 import android.app.Activity를 작성하면 컴파일러는 특정 SDK Platform의 android.jar에서 이 클래스를 가져옵니다. 필요한 API Level의 플랫폼이 설치되지 않으면 코드가 컴파일되지 않습니다.

Google은 각 안정적인 Android 버전에 대해 새 SDK Platform을 릴리스합니다. 그 역사는 Android 1.0(API 1)부터 Android 15(API 35)까지 35개 이상의 API Level을 포함합니다. 각 플랫폼은 하위 호환됩니다. API Level 21용으로 작성된 코드는 API Level 35에서 실행되지만 그 반대는 불가능합니다.

각 버전마다 별도의 SDK Platform이 필요한 이유

Android는 빠르게 진화합니다. 각 버전은 새 API를 추가하고, 기존 동작을 변경하며, 제한 사항을 도입합니다. 예를 들어, Android 10(API 29)은 Scoped Storage를 도입했고, Android 12(API 31)는 SplashScreen API를, Android 14(API 34)는 필수 BroadcastReceiver 플래그를 도입했습니다. 개발자는 이러한 기능을 사용하기 위해 현재 플랫폼에 대해 애플리케이션을 컴파일해야 합니다.

동시에 애플리케이션은 이전 OS 버전에서 실행될 수 있습니다. 이를 위해 Gradle에 minSdk(애플리케이션이 실행되는 최소 API Level)가 지정됩니다. 코드는 버전 확인 및 조건부 API 호출을 사용합니다. 이 접근 방식은 새 기능을 잃지 않고 호환성을 보장합니다.

SDK Platform 구성: 주요 구성 요소

SDK Platform은 단일 파일이 아니라 애플리케이션의 컴파일, 빌드 및 테스트를 함께 보장하는 구성 요소 집합입니다. 주요 요소는 android.jar — 이 버전에 포함된 Android API 클래스가 있는 아카이브입니다. 이 파일은 Kotlin 또는 Java 컴파일러에 연결되며 개발자가 사용할 수 있는 클래스, 메서드 및 어노테이션을 결정합니다.

시스템 이미지 및 에뮬레이터

각 SDK Platform에는 Android Virtual Device 에뮬레이터용 System Image(운영 체제 이미지)가 포함됩니다. 해당 이미지가 없으면 에뮬레이터는 필요한 API Level의 가상 장치를 시작할 수 없습니다. System Images에는 여러 유형이 있습니다: Google APIs(Google 서비스 포함), Google Play(Play Store 포함) 및 AOSP(Google 서비스가 없는 순수 Android).

빌드 및 디버그 도구

SDK Platform에는 이 API Level에 최적화된 Build-Tools 및 Platform-Tools 버전이 포함됩니다. Build-Tools에는 aapt2(Android Asset Packaging Tool), dx/d8(Dalvik/ART 컴파일러) 및 ApkSigner가 포함됩니다. Platform-Tools는 ADB(Android Debug Bridge), fastboot 및 SQLite를 제공합니다. 이러한 도구는 SDK Manager를 통해 SDK Platform과 독립적으로 업데이트됩니다.

플랫폼 리소스

각 플랫폼에는 표준 Android 리소스(시스템 테마, 스타일, 애니메이션, 색상 및 치수)가 포함됩니다. 이러한 리소스는 컴파일 중에 사용됩니다. 개발자가 @android:style/Theme.Material.Light를 참조하면 빌드 시스템은 SDK Platform 리소스에서 정의를 가져옵니다. 이는 모든 장치에서 시스템 구성 요소의 일관된 모양을 보장합니다.

API Level 및 SDK Platform 버전

API Level은 Android SDK 버전의 정수 식별자입니다. 각 Android 릴리스는 단조 증가하는 하나의 API Level에 해당합니다. 개발자는 build.gradle의 세 가지 주요 매개변수(compileSdk, minSdk, targetSdk)에서 API Level을 지정합니다. 이러한 매개변수의 선택은 사용 가능한 API와 시스템이 애플리케이션을 처리하는 방식을 결정합니다.

Google은 minSdk를 현재 배포 임계값보다 낮게 유지하지 않도록 권장합니다. Android Studio Distribution Dashboard(2026)에 따르면 약 95%의 장치가 Android 8.0(API 26) 이상에서 실행됩니다. compileSdk는 최신 안정 버전이어야 합니다. 이렇게 하면 새 API에 액세스할 수 있고 lint 검사가 더 이상 사용되지 않는 메서드를 감지할 수 있습니다.

API Level의 진화: 주요 변경 사항

새 API Level마다 Google은 중요한 변경 사항을 도입합니다. Android 6.0(API 23)은 런타임 권한을 추가했습니다. 애플리케이션이 설치 시가 아니라 실행 중에 권한을 요청합니다. Android 8.0(API 26)은 자동 완성 양식 및 알림 채널을 도입했습니다. Android 12(API 31)는 인텐트에 대한 접근 방식을 근본적으로 변경했습니다. SplashScreen API와 exported 속성을 통한 구성 요소 내보내기가 등장했습니다. Android 14(API 34)는 BroadcastReceiver에 플래그 지정을 의무화하고 포그라운드 서비스에 엄격한 제한을 도입했습니다.

API Level의 역사를 이해하면 개발자가 올바른 호환성 전략을 선택하는 데 도움이 됩니다. 애플리케이션이 compileSdk 35를 사용하지만 minSdk 26인 경우 코드는 Build.VERSION.SDK_INT를 통한 버전 확인 후에만 API 35 메서드를 호출할 수 있습니다. 이 접근 방식을 버전 게이트 개발이라고 하며 업계 표준입니다.

SDK Manager: 설치 및 설정

SDK Manager는 Android SDK 구성 요소를 관리하기 위한 도구입니다: 새 SDK Platform 설치, 기존 업데이트 및 오래된 항목 제거. SDK Manager는 Android Studio의 그래픽 인터페이스와 sdkmanager를 통한 명령줄 도구로 사용할 수 있습니다. 명령줄 SDK Manager는 그래픽 인터페이스가 없는 CI/CD 파이프라인에서 사용하기 편리합니다.

SDK Manager는 플랫폼을 Android SDK 디렉토리에 설치합니다. 기본 위치는 Linux 및 macOS에서 $HOME/Android/Sdk, Windows에서 %LOCALAPPDATA%\Android\Sdk입니다. platforms 디렉토리 안에는 android-{API Level} 폴더가 있으며, 각 폴더에는 완전한 SDK Platform이 포함되어 있습니다.

sdkmanager를 통한 SDK Platform 설치

sdkmanager 명령은 "platforms;android-{API}" 형식의 패키지 식별자를 받습니다. 예를 들어, SDK Platform 35를 설치하는 명령은 다음과 같습니다:

# API Level 35용 SDK Platform 설치
sdkmanager "platforms;android-35"

# 하나의 명령으로 여러 플랫폼 설치
sdkmanager "platforms;android-34" "platforms;android-33" "platforms;android-31"

# 설치된 플랫폼 목록
sdkmanager --list_installed | grep platforms

# 이전 플랫폼 제거
sdkmanager --uninstall "platforms;android-28"

Gradle을 통한 자동 설치

최신 Android 프로젝트는 Gradle Plugin을 사용하며, 첫 번째 빌드 시 SDK Platform을 자동으로 설치할 수 있습니다. 이렇게 하려면 build.gradle에서 compileSdk를 지정하고 로컬 구성에 SDK 디렉토리를 추가해야 합니다. Android Studio는 프로젝트를 열 때 누락된 플랫폼 설치도 제안합니다. Gradle 동기화 창에서 "Install SDK Platform" 버튼을 클릭하기만 하면 됩니다.

SDK Manager를 통해 정기적으로 SDK Platform을 업데이트하는 것이 중요합니다. 플랫폼과 함께 Build-Tools 및 Platform-Tools도 업데이트되어 빌드 성능 및 디버깅 안정성에 영향을 줍니다. Google은 2~3주마다 SDK 업데이트를 확인할 것을 권장합니다. 특히 Google Play에 새 버전의 애플리케이션을 게시하기 전에 중요합니다.

에뮬레이터용 시스템 이미지 설정

특정 API Level로 에뮬레이터를 실행하려면 동일한 버전의 System Image를 설치해야 합니다. SDK Manager는 다양한 아키텍처(x86_64, arm64-v8a) 및 유형(Google APIs, Google Play, AOSP)의 이미지를 다운로드할 수 있습니다. 이미지를 다운로드한 후 AVD Manager가 이를 기반으로 가상 장치를 만듭니다.

# API 35용 Google APIs가 포함된 System Image 설치
sdkmanager "system-images;android-35;google_apis;x86_64"

# 명령줄을 통해 AVD 생성
avdmanager create avd -n pixel8 -k "system-images;android-35;google_apis;x86_64"

# 생성된 AVD 목록
avdmanager list avd

Gradle의 compileSdk, targetSdk 및 minSdk

build.gradle의 세 가지 매개변수는 애플리케이션이 SDK Platform과 작동하는 방식을 정의합니다. compileSdk는 컴파일에 사용되는 API Level입니다. 이 매개변수는 코드에서 사용할 수 있는 Android API 클래스를 지정합니다. compileSdk는 세 가지 중 가장 최신이어야 하며 런타임 동작에 영향을 미치지 않습니다. 애플리케이션은 컴파일되지만 장치에서 사용 가능한 API만 사용합니다.

minSdk는 애플리케이션을 설치할 수 있는 최소 API Level입니다. Google Play는 minSdk보다 낮은 버전의 장치에 애플리케이션 설치를 허용하지 않습니다. 이 매개변수는 호환성 임계값을 정의하고 사용자 범위에 영향을 줍니다. minSdk가 낮을수록 더 많은 장치가 지원되지만 검사 없이 사용할 수 있는 새 API가 줄어듭니다.

targetSdk는 애플리케이션이 테스트된 API Level입니다. Android 시스템은 targetSdk를 사용하여 동작 변경을 적용합니다. 애플리케이션이 새 API Level로 업데이트되지 않은 경우 시스템은 이전 버전용 호환 모드를 활성화합니다. Google Play는 targetSdk가 특정 수준 이상이어야 합니다. 2026년 기준으로 API 34(Android 14)입니다.

Gradle 구성 예제

android {
    compileSdk 35

    defaultConfig {
        applicationId "com.example.app"
        minSdk 26
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

// Android SDK 버전은 SDK Manager를 통해 설치해야 합니다
// sdkmanager "platforms;android-35"

compileSdk, minSdk 및 targetSdk 선택 방법

선택 전략은 프로젝트 목표에 따라 다릅니다. 새 애플리케이션의 경우: compileSdk — 최신 안정 버전(2026년 초 기준 35), minSdk — API 26(Android 8.0, 장치의 95% 커버), targetSdk — 최신 안정 버전. 기존 애플리케이션 업데이트의 경우: compileSdk는 즉시 올리고, targetSdk — 모든 동작 변경 테스트 후, minSdk — 이전 장치 지원을 중단해야 하는 경우에만.

Google은 새 Android 버전 출시 후 1년 이내에 targetSdk를 업데이트하도록 요구합니다. 이 요구 사항을 충족하지 않는 애플리케이션은 Google Play에서 업데이트를 게시할 수 없습니다. 마감일을 추적하려면 공식 Android OS 업데이트 캘린더를 사용하세요.

코드에서 SDK Platform 작업 예제

다른 Android 버전용으로 개발할 때 API 가용성을 고려해야 합니다. 애플리케이션이 compileSdk 35를 사용하지만 API 31 장치에서 실행되는 경우 API 34에서 추가된 메서드를 호출하면 NoSuchMethodError 또는 AbstractMethodError가 발생합니다. 새 API를 안전하게 호출하기 위해 Build.VERSION.SDK_INT를 통한 버전 확인이 사용됩니다.

런타임에서 API Level 확인

class FeatureChecker {
    fun registerNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            // 알림 채널은 API 26부터 사용 가능
            val channel = NotificationChannel(
                "updates",
                "업데이트",
                NotificationManager.IMPORTANCE_DEFAULT
            )
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

@RequiresApi를 사용한 새 API 활용

특정 버전에서만 호출되는 메서드의 경우 @RequiresApi 어노테이션을 사용하세요. 이는 lint 검사에 메서드가 안전하다고 알리고 경고를 비활성화합니다. SDK_INT 확인과 결합하면 어노테이션이 코드를 더 깔끔하게 만들고 검토자가 이해하기 쉽게 만듭니다.

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun scheduleExactAlarm(manager: AlarmManager, time: Long) {
    // API 34: SCHEDULE_EXACT_ALARM 플래그가 있는 scheduleExact
    if (manager.canScheduleExactAlarms()) {
        manager.setExact(AlarmManager.RTC_WAKEUP, time, pendingIntent)
    } else {
        // SCHEDULE_EXACT_ALARM 권한 요청
        val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
        context.startActivity(intent)
    }
}

fun safeScheduleAlarm(context: Context, triggerTime: Long) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleExactAlarm(getAlarmManager(context), triggerTime)
    } else {
        // 권한 확인 없는 이전 setExact 메서드
        getAlarmManager(context).setExact(AlarmManager.RTC_WAKEUP, triggerTime, pendingIntent)
    }
}

설치된 SDK Platform 확인

개발자 장치나 CI에 설치된 SDK Platform 버전을 알아야 하는 경우가 있습니다. 이는 ADB를 통해 또는 애플리케이션 코드에서 프로그래밍 방식으로 수행할 수 있습니다. 장치의 API Level을 알면 버전별 동작 테스트에 도움이 됩니다.

fun logDeviceInfo() {
    with (Build.VERSION) {
        Log.d("SDK_Demo", "SDK_INT: $SDK_INT")
        Log.d("SDK_Demo", "RELEASE: $RELEASE")
        Log.d("SDK_Demo", "CODENAME: $CODENAME")
        Log.d("SDK_Demo", "PREVIEW_SDK_INT: $PREVIEW_SDK_INT")
    }
    // 출력: SDK_INT: 35, RELEASE: 15, CODENAME: REL
}