targetSdkVersion: 주요 개념, 동작 변경 및 Google Play

Android에서 targetSdkVersion이란?

targetSdkVersion은 build.gradle의 정수 매개변수로, 앱이 테스트된 API Level을 선언합니다. Android 시스템은 이 매개변수를 사용하여 런타임에 앱에 어떤 동작 변경을 적용할지 결정합니다. targetSdkVersion = 33이면 Android는 API 33까지 도입된 모든 동작 변경을 적용하지만 API 34+의 변경 사항은 적용하지 않습니다. targetSdkVersion = 34이면 API 34까지의 변경 사항이 적용되는 식입니다.

targetSdkVersion과 minSdkVersion의 주요 차이점은 작동 메커니즘입니다. minSdk는 설치 중 한 번 확인되며 조건이 충족되지 않으면 설치를 차단합니다. targetSdkVersion은 앱이 실행 중인 Android 버전과 관계없이 각 기기에서 시스템의 런타임 동작에 영향을 미칩니다. targetSdk 31이 설정된 동일한 앱이 Android 13, 14, 15에서 다르게 동작하는 이유는 31 이상의 동작 변경이 비활성화되어 있기 때문입니다.

targetSdkVersion 메커니즘은 Android에 내장된 하위 호환성 도구입니다. 이것이 없으면 OS 업데이트 때마다 수천 개의 오래된 앱이 손상됩니다. Google은 Android 2.1(API Level 7)에서 이 메커니즘을 도입했으며 그 이후로 기존 애플리케이션을 손상시키지 않고 새로운 보안, 개인정보 보호 및 리소스 관리 규칙을 도입하는 표준 방법으로 사용하고 있습니다.

// build.gradle.kts — defaultConfig의 targetSdkVersion
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36   // Android 16에서 테스트됨
        versionCode = 1
        versionName = "1.0.0"
    }
}

// 코드에서 현재 targetSdk 확인
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion에 앱의 targetSdk가 포함됨
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

예제에서 targetSdk = 36은 Android 16의 모든 동작 변경을 활성화합니다. 코드는 context.applicationInfo.targetSdkVersion을 통해 targetSdkVersion을 확인합니다. 이를 통해 어떤 호환성 모드가 활성화되어 있는지 동적으로 결정할 수 있습니다. 헬퍼 함수는 호출 애플리케이션의 targetSdk에 적응해야 하는 라이브러리에 유용합니다.

동작 변경: targetSdk가 앱에 미치는 영향

동작 변경(behavioural changes)은 targetSdkVersion >= 특정 API Level인 앱에만 적용되는 Android 시스템 동작 수정입니다. 새로운 주요 Android 릴리스마다 동작 변경이 도입되며, 앱이 targetSdk를 업데이트하지 않으면 이러한 변경 사항이 적용되지 않습니다. 이 메커니즘을 통해 개발자는 새 OS 릴리스와 동기화하지 않고 자신의 페이스에 맞춰 앱을 업데이트할 수 있습니다.

Scoped Storage(API 29)는 가장 중요한 동작 변경 중 하나입니다. targetSdk 29+ 앱은 공유 디렉터리(Pictures, Downloads, Music, Documents)에 직접 파일 액세스할 수 없습니다. 대신 멀티미디어에는 MediaStore, 임의 파일에는 SAF(Storage Access Framework), 개인 스토리지에는 getExternalFilesDir()이 사용됩니다. targetSdk 28 이하의 오래된 앱은 레거시 Full Storage Access로 계속 작동하지만 이는 보안 위험을 초래합니다.

POST_NOTIFICATIONS(API 33)은 알림 전송을 위한 런타임 권한입니다. targetSdk 33+ 앱은 표준 대화상자를 통해 사용자에게 Manifest.permission.POST_NOTIFICATIONS 권한을 요청해야 합니다. 권한이 부여되지 않으면 NotificationManager.silent()가 사용자에게 알림을 표시하지 않습니다. Android 13+에서 이 권한이 없으면 푸시 알림과 로컬 알림이 표시되지 않아 사용자 참여도가 크게 떨어질 수 있습니다.

현재 targetSdk 확인 방법

targetSdkVersion 값은 ADB를 통해 얻을 수 있습니다: adb shell dumpsys package com.example.myapp | grep targetSdk 명령어는 targetSdk=34를 출력합니다. 코드에서 context.getApplicationInfo().targetSdkVersion은 정수를 반환합니다. 분석을 위해 각 세션에서 실제로 어떤 동작 변경이 활성화되어 있는지 이해하려면 targetSdk를 android.os.Build.VERSION.SDK_INT와 함께 로깅하는 것이 유용합니다.

Google Play의 targetSdkVersion 요구사항 (2026년)

Google Play는 게시된 모든 앱에 대해 targetSdkVersion 필수 요구사항을 설정합니다. 2024년 8월부터 최소 targetSdk = 33(Android 13)입니다. 2025년 8월부터 targetSdk = 34입니다. 2026년 8월부터 Google이 targetSdk = 35(Android 15)를 요구할 것으로 예상됩니다. 새로운 앱과 기존 앱의 업데이트는 이러한 요구사항을 준수해야 하며, 그렇지 않으면 콘솔에서 게시를 차단합니다. 이는 Google Play 정책이지 Android Runtime 제한이 아닙니다: targetSdk 34 앱은 Android 16에서 실행될 수 있지만 Play Store에 게시할 수는 없습니다.

Android App Bundle(AAB)은 2021년 8월부터 필수 게시 형식입니다. APK는 더 이상 Google Play에서 허용되지 않습니다(150MB를 초과하는 앱 및 일부 레거시 프로젝트 제외). AAB 형식을 통해 Google은 각 API Level 및 화면 밀도에 최적화된 APK를 생성하여 다운로드 크기를 15-30% 줄일 수 있습니다. targetSdk를 확인하기 위해 Google Play는 AAB 매니페스트를 분석하고 준수하지 않는 경우 최소 필수 값과 함께 오류를 발생시킵니다.

Google Play Console은 새 AAB를 업로드할 때뿐만 아니라 기존 앱을 업데이트할 때도 targetSdkVersion을 확인합니다. 앱의 targetSdk가 33이고 Google이 최소 임계값을 34로 올리면 targetSdk를 올릴 때까지 업데이트를 출시할 수 없습니다. 오랫동안 업데이트되지 않은 앱의 경우 Google Play에서 자동으로 게시를 취소(unpublish)할 수 있습니다.

오류 없이 targetSdkVersion 업데이트하는 방법

targetSdkVersion 업데이트는 build.gradle에서 숫자만 변경하는 것이 아닙니다. 코드를 미리 준비하지 않으면 각 동작 변경이 기존 기능을 손상시킬 수 있습니다. 특히 앱이 크고 많은 시스템 API를 사용하는 경우 Google Play 마감일 3-6개월 전에 준비를 시작하는 것이 좋습니다.

단계별 프로세스: 1단계 — Android Developers 문서("Behavioural Changes by API Level" 페이지)에서 새 API Level의 동작 변경을 연구합니다. 2단계 — targetSdk-update 브랜치를 만들고 targetSdk를 새 값으로 변경합니다. 3단계 — 새 API Level의 에뮬레이터 또는 기기에서 앱을 실행하고 변경 사항과 관련된 모든 기능을 확인합니다. 4단계 — 오류를 수정합니다: 권한 추가, 파일 처리 변경, 매니페스트 업데이트.

5단계 — 오래된 기기에서 테스트합니다. targetSdk를 올려도 새 targetSdk보다 낮은 API Level의 기기에는 영향을 미치지 않지만, 동작 변경은 API Level >= targetSdk인 모든 기기에 적용됩니다. targetSdk를 33에서 34로 올린 경우 API 34+ 기기에서는 API 34의 동작 변경이 활성화됩니다. API 33 기기에서는 아무것도 변경되지 않습니다.

// targetSdk 35 준비: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox는 API 35부터 Advertising ID를 제한함
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — 식별자 사용 불가, MeasurementManager 사용
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // 확인: 어떤 동작 변경이 활성화되어 있는지
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

AdsManager 클래스는 Privacy Sandbox(API 35) 준비를 보여줍니다. Advertising ID는 API 35부터 targetSdk 35+에서 사용할 수 없게 됩니다. getActiveChanges 함수는 동작 변경 확인의 올바른 패턴을 보여줍니다: 기기의 SDK_INT와 앱의 targetSdk를 모두 확인해야 합니다. 두 조건이 모두 일치해야 변경 사항이 실제로 활성화됩니다.

Android 15 (API 35): 주요 동작 변경

Android 15(API 35, Vanilla Ice Cream)는 targetSdk를 35로 업데이트할 때 개발자가 고려해야 할 몇 가지 중요한 동작 변경을 도입합니다. 첫째 — Privacy Sandbox for Android. 이는 Advertising ID를 더 프라이빗한 API로 대체하려는 Google의 이니셔티브입니다: Topics API(사용자 관심사), Protected Audience(리타겟팅), Attribution Reporting(전환). API 35부터 Advertising ID는 안정적인 식별자가 아니게 되며 null 값을 반환할 수 있습니다.

두 번째 변경 — Foreground Service Types(API 34, API 35에서 계속). API 34부터 targetSdk 34+의 모든 앱은 매니페스트에서 포그라운드 서비스 유형을 지정해야 합니다: dataSync, systemExempted, shortService, location, mediaPlayback 등. 이렇게 하지 않으면 시스템이 ForegroundServiceTypeNotAllowedException을 발생시킵니다. API 35에서는 새로운 health 유형이 추가되고 기존 유형의 검증이 강화되었습니다. 모든 포그라운드 서비스를 검토해야 합니다.

세 번째 변경 — SCHEDULE_EXACT_ALARM 제한. API 35부터 targetSdk 35+ 앱은 명시적인 사용자 권한 없이 SCHEDULE_EXACT_ALARM을 사용할 수 없습니다. 시스템이 대화상자를 표시하고 사용자가 정확한 스케줄링을 승인해야 합니다. 알람 및 타이머의 경우 UX에 추가 단계가 필요함을 의미합니다. 대안으로 10분 버퍼가 있는 부정확한 알람을 사용할 수 있습니다.

// Android 15 (API 35): SCHEDULE_EXACT_ALARM 확인
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: 사용자 권한 필요
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // API 35 미만 — 권한 없이 정확한 알람 사용 가능
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox와 알람 제한은 API 35의 가장 중요한 두 가지 동작 변경입니다. 광고 SDK는 Topics API 및 Attribution Reporting으로 마이그레이션해야 합니다. 알람 및 알림이 있는 앱의 경우 권한 대화상자에 대한 UX 적응이 필요합니다. 이러한 변경 사항을 무시하면 Android 15에서 런타임 앱 충돌이 발생하거나 광고 수익 창출이 중단됩니다.

targetSdk와 compileSdk의 차이

targetSdkVersion과 compileSdkVersion의 차이는 Android 개발자 사이에서 가장 흔한 혼란 원인 중 하나입니다. compileSdkVersion은 코드가 컴파일되는 SDK 버전입니다. 컴파일 시 사용 가능한 API를 결정하지만 런타임 동작에는 영향을 미치지 않습니다. targetSdkVersion은 앱이 테스트된 버전으로, 런타임에 어떤 동작 변경이 적용되는지 결정합니다. compileSdk는 targetSdk보다 높거나 같을 수 있으며 그래야 합니다.

규칙은 간단합니다: compileSdk >= targetSdk >= minSdk. compileSdk는 일반적으로 최신 안정 API Level(2026년에는 36)과 같습니다. targetSdk는 테스트한 버전 중에서 가능한 한 높아야 합니다. minSdk는 최대 도달 범위를 위해 가능한 한 낮아야 합니다. compileSdk를 올려도 동작 변경 테스트가 필요하지 않습니다 — 컴파일러가 새 API에 액세스할 수 있게 될 뿐입니다. targetSdk를 올리려면 모든 동작 변경에 대한 전체 테스트 주기가 필요합니다.

실제로: Android 16(API 36)의 새 API를 사용하고 싶지만 API 36의 동작 변경을 아직 테스트하지 않은 경우 compileSdk = 36, targetSdk = 35로 설정합니다. 코드는 새 API로 컴파일되지만 API 36의 동작 변경은 적용되지 않습니다. 모든 변경 사항을 테스트한 후 targetSdk를 36으로 올리십시오.