<uses-sdk>

Google Play는 앱 매니페스트에 선언된 <uses-sdk> 속성을 사용하여 플랫폼 버전 요구사항을 충족하지 않는 기기에서 앱을 필터링합니다. 이러한 속성을 설정하기 전에 Google Play 필터를 이해해야 합니다.

구문:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
포함된 위치:
<manifest>
설명:

하나 이상의 Android 플랫폼 버전과의 애플리케이션 호환성을 API 수준 정수로 표시할 수 있습니다. 애플리케이션에서 표시한 API 수준은 특정 Android 시스템의 API 수준과 비교되며, 이는 Android 기기마다 다를 수 있습니다.

이름과 달리 이 요소는 소프트웨어 개발 키트 (SDK) 또는 Android 플랫폼의 버전 번호가 아니라 API 수준을 지정하는 데 사용됩니다. API 수준은 항상 단일 정수입니다. 연결된 Android 버전 번호에서 API 수준을 가져올 수 없습니다. 예를 들어 주 버전 또는 주 버전과 부 버전의 합계와 같지 않습니다.

애플리케이션 버전 관리 문서도 읽어보세요.

속성:
android:minSdkVersion
애플리케이션이 실행하는 데 필요한 최소 API 수준을 지정하는 정수입니다. Android 시스템은 시스템의 API 수준이 이 속성에 지정된 값보다 낮으면 사용자가 애플리케이션을 설치하지 못하게 합니다. 항상 이 속성을 선언하세요.

주의: 이 속성을 선언하지 않으면 시스템은 기본값을 '1'로 가정합니다. 이는 애플리케이션이 모든 Android 버전과 호환됨을 나타냅니다. API 레벨이 호환되지 않고 적절한 minSdkVersion를 선언하지 않은 경우, 호환되지 않는 API 수준의 시스템에 설치된 경우 애플리케이션이 사용할 수 없는 API에 액세스하려고 하면 런타임 중에 비정상 종료됩니다. 따라서 minSdkVersion 속성에서 적절한 API 수준을 선언해야 합니다.

android:targetSdkVersion
애플리케이션이 대상으로 하는 API 수준을 지정하는 정수입니다. 설정하지 않을 경우 기본값은 minSdkVersion에 주어진 값과 동일합니다.

이 속성은 개발자가 타겟 버전을 테스트했음을 시스템에 알립니다. 또한 시스템은 앱과 타겟 버전의 향후 호환성을 유지하기 위해 호환성 동작을 사용 설정하지 않습니다. 더 낮은 버전 (minSdkVersion까지)에서는 여전히 애플리케이션을 실행할 수 있습니다.

Android의 새 버전이 나올 때마다 일부 동작은 물론, 심지어 모양까지 변경될 수 있습니다. 그러나 플랫폼의 API 수준이 앱의 targetSdkVersion에서 선언한 버전보다 높은 경우 시스템은 앱이 예상대로 계속 작동하도록 호환성 동작을 사용 설정할 수 있습니다. 실행 중인 플랫폼의 API 수준과 일치하는 targetSdkVersion을 지정하면 이러한 호환성 동작을 사용 중지할 수 있습니다.

예를 들어 이 값을 '11' 이상으로 설정하면 Android 3.0 이상에서 실행될 때 시스템에서 앱에 Holo 기본 테마를 적용할 수 있으며, 큰 화면에서 실행될 때는 화면 호환 모드도 사용 중지합니다. API 수준 11 지원이 대형 화면을 암시적으로 지원하기 때문입니다.

이 속성에 설정한 값에 기반하여 시스템에서 사용 설정할 수 있는 호환성 동작이 많이 있습니다. 이러한 일부 동작은 Build.VERSION_CODES 참조에서 플랫폼 버전별로 설명합니다.

각 Android 버전과 함께 애플리케이션을 유지관리하려면 최신 API 수준에 맞게 이 속성 값을 높인 다음 해당 플랫폼 버전에서 애플리케이션을 철저히 테스트합니다.

도입 시기: API 수준 4

android:maxSdkVersion
애플리케이션이 실행되도록 설계된 최대 API 수준을 지정하는 정수입니다.

Android 1.5, 1.6, 2.0, 2.0.1에서 애플리케이션을 설치할 때와 시스템 업데이트 후에 애플리케이션 유효성을 다시 검사할 때 시스템이 이 속성 값을 확인합니다. 어느 경우든 애플리케이션의 maxSdkVersion 속성이 시스템에서 사용하는 API 수준보다 낮으면 시스템은 애플리케이션 설치를 허용하지 않습니다. 시스템 업데이트 후에 유효성을 다시 검사하는 경우 실질적으로 기기에서 애플리케이션이 삭제됩니다.

시스템 업데이트 후에 이 속성이 애플리케이션에 어떻게 영향을 미치는지 다음의 예로 알아보겠습니다.

매니페스트에 maxSdkVersion="5"를 선언하는 애플리케이션이 Google Play에 게시되어 있습니다. Android 1.6 (API 수준 4)을 실행하는 기기의 사용자가 앱을 다운로드하고 설치합니다. 몇 주 후에 사용자는 Android 2.0 (API 수준 5)으로 무선 시스템 업데이트를 받게 됩니다. 업데이트 설치 후에 시스템이 애플리케이션의 maxSdkVersion을 확인하고 유효성 검사를 성공적으로 마칩니다.

애플리케이션이 정상 작동합니다. 그러나 어느 정도 시간이 흐른 후 기기가 Android 2.0.1 (API 수준 6)이라는 다른 시스템 업데이트를 수신합니다. 업데이트 후에는 시스템의 자체 API 수준 (6)이 애플리케이션에서 지원하는 최대 수준(5)보다 높으므로 시스템에서 더 이상 애플리케이션의 유효성을 다시 검사할 수 없습니다. 시스템은 애플리케이션이 사용자에게 보이지 않게 하여 실질적으로 기기에서 애플리케이션을 삭제합니다.

경고: 이 속성은 선언하지 않는 것이 좋습니다. 첫째, Android 플랫폼의 새 버전이 출시될 때 해당 버전으로 애플리케이션 배포를 차단하는 수단으로 이 속성을 설정할 필요가 없습니다. 플랫폼의 새 버전은 이전 버전과 완전히 호환되도록 설계되었습니다. 애플리케이션이 표준 API만 사용하고 개발 권장사항을 따른 경우 새 버전에서 제대로 작동합니다. 둘째, 경우에 따라 이 속성을 선언하면 시스템이 상위 API 수준으로 업데이트된 후에 애플리케이션이 사용자 기기에서 삭제될 수 있습니다. 애플리케이션이 설치될 대부분의 기기는 정기적인 시스템 업데이트를 무선으로 수신하므로 이 속성을 설정하기 전에 애플리케이션에 미치는 영향을 고려하세요.

도입 시기: API 수준 4

일부 Android 버전 (Android 2.0.1 이상)은 설치 또는 유효성 재검사 중에 maxSdkVersion 속성을 확인하거나 적용하지 않습니다. 하지만 Google Play는 다운로드할 수 있는 애플리케이션을 사용자에게 제공할 때 이 속성을 필터로 계속 사용합니다.
도입 수준:
API 수준 1

API 수준이란 무엇인가요?

API 수준은 Android 플랫폼 버전에서 제공하는 프레임워크 API 버전을 고유하게 식별하는 정수 값입니다.

Android 플랫폼은 애플리케이션이 기본 Android 시스템과 상호작용하는 데 사용할 수 있는 프레임워크 API를 제공합니다. 프레임워크 API는 다음 요소로 구성되어 있습니다.

  • 핵심 패키지 및 클래스 집합
  • 매니페스트 파일을 선언하는 데 사용되는 XML 요소 및 속성 집합
  • 리소스를 선언 및 액세스하는 데 사용되는 XML 요소 및 속성 집합
  • 인텐트 집합
  • 애플리케이션이 요청할 수 있는 권한 및 시스템에 포함된 권한 적용 집합

연속된 각 Android 플랫폼 버전에는 제공하는 Android 애플리케이션 프레임워크 API 업데이트가 포함될 수 있습니다.

프레임워크 API 업데이트는 새 API가 이전 API 버전과의 호환성을 유지하도록 설계되었습니다. 즉, 대부분의 API 변경사항은 추가된 것이며 새 기능 또는 대체 기능을 소개합니다. API 요소가 업그레이드되면 대체된 이전 요소는 지원이 중단되지만 삭제되지는 않으므로 기존 애플리케이션에서 계속 사용할 수 있습니다.

극히 드물게 API 요소가 수정 또는 삭제되지만 이러한 변경은 일반적으로 API 견고성과 애플리케이션 또는 시스템 보안을 지원하기 위해서만 필요합니다. 이전 버전의 모든 기타 API 요소는 수정 없이 새 버전에 제공됩니다.

Android 플랫폼이 제공하는 프레임워크 API는 API 수준이라는 정수 식별자를 사용하여 지정됩니다. 각 Android 플랫폼 버전은 모든 이전 API 수준(API 수준 1까지)을 암시적으로 지원하지만 정확히 하나의 API 수준을 지원합니다. Android 플랫폼의 최초 버전은 API 수준 1을 제공했으며 후속 출시에서는 API 수준이 증가했습니다.

다음 표에는 각 Android 플랫폼 버전에서 지원하는 API 수준이 나와 있습니다. 각 버전을 실행하는 기기의 상대적인 숫자에 관한 자세한 내용은 배포 대시보드를 참고하세요.

플랫폼 버전API 수준버전 코드Notes
Android 15 API 34 → DP1 VANILLA_ICE_CREAM 플랫폼 하이라이트
Android 14 34 UPSIDE_DOWN_CAKE 플랫폼 하이라이트
Android 13 33 TIRAMISU 플랫폼 하이라이트
Android 12 32 S_V2 플랫폼 하이라이트
31 S 플랫폼 하이라이트
Android 11 30 R 플랫폼 하이라이트
Android 10 29 Q 플랫폼 하이라이트
Android 9 28 P 플랫폼 하이라이트
Android 8.1 27 O_MR1 플랫폼 하이라이트
Android 8.0 26 O 플랫폼 하이라이트
Android 7.1.1
Android 7.1
25 N_MR1 플랫폼 하이라이트
Android 7.0 24 N 플랫폼 하이라이트
Android 6.0 23 M 플랫폼 하이라이트
Android 5.1 22 LOLLIPOP_MR1 플랫폼 하이라이트
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH 웨어러블 기기 전용 KitKat
Android 4.4 19 KITKAT 플랫폼 하이라이트
Android 4.3 18 JELLY_BEAN_MR2 플랫폼 하이라이트
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 플랫폼 하이라이트
Android 4.1, 4.1.1 16 JELLY_BEAN 플랫폼 하이라이트
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 플랫폼 하이라이트
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 플랫폼 하이라이트
Android 3.0.x 11 HONEYCOMB 플랫폼 하이라이트
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 플랫폼 하이라이트
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO 플랫폼 하이라이트
Android 2.1.x 7 ECLAIR_MR1 플랫폼 하이라이트
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT 플랫폼 하이라이트
Android 1.5 3 CUPCAKE 플랫폼 하이라이트
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Android에서 API 수준 사용

API 수준 식별자는 사용자와 애플리케이션 개발자에게 최상의 환경을 보장하는 데 중요한 역할을 합니다.

  • 이를 통해 Android 플랫폼이 지원하는 최대 프레임워크 API 버전을 설명할 수 있습니다.
  • 이를 통해 애플리케이션은 필요한 프레임워크 API 버전을 설명할 수 있습니다.
  • 시스템에서 버전 비호환 애플리케이션이 설치되지 않도록 사용자 기기의 애플리케이션 설치를 협상할 수 있습니다.

각 Android 플랫폼 버전은 API 수준 식별자를 내부적으로 Android 시스템 자체에 저장합니다.

애플리케이션은 프레임워크 API에서 제공하는 매니페스트 요소(<uses-sdk>)를 사용하여 실행할 수 있는 최소 및 최대 API 수준과 지원하도록 설계된 기본 API 수준을 설명할 수 있습니다. 이 요소는 다음과 같은 3가지 주요 속성을 제공합니다.

  • android:minSdkVersion: 애플리케이션이 실행할 수 있는 최소 API 수준입니다. 기본값은 '1'입니다.
  • android:targetSdkVersion: 애플리케이션이 실행되는 API 수준입니다. 경우에 따라 최소 API 수준에 정의된 것만 사용하도록 제한하기보다는 애플리케이션이 대상 API 수준에서 정의된 매니페스트 요소나 동작을 사용하도록 허용합니다.
  • android:maxSdkVersion: 애플리케이션이 실행할 수 있는 최대 API 수준입니다. 중요: 사용하기 전에 이 페이지의 이 속성에 대한 정보를 읽어보세요.

예를 들어 애플리케이션이 실행하는 데 필요한 최소 시스템 API 수준을 지정하기 위해 애플리케이션은 매니페스트에 android:minSdkVersion 속성이 있는 <uses-sdk> 요소를 포함합니다. android:minSdkVersion의 값은 애플리케이션이 실행될 수 있는 최초 Android 플랫폼 버전의 API 수준에 해당하는 정수입니다.

사용자가 애플리케이션을 설치하려고 하거나 시스템 업데이트 후 애플리케이션의 유효성을 재확인할 때 Android 시스템은 먼저 애플리케이션의 매니페스트에서 <uses-sdk> 속성을 확인하고 값을 자체 내부 API 수준과 비교합니다. 시스템에서는 다음 조건이 충족되는 경우에만 설치가 시작됩니다.

  • android:minSdkVersion 속성이 선언된 경우 그 값은 시스템의 API 수준 정수보다 작거나 같습니다. 선언하지 않으면 시스템은 애플리케이션에 API 수준 1이 필요하다고 가정합니다.
  • android:maxSdkVersion 속성이 선언된 경우 그 값은 시스템의 API 수준 정수보다 크거나 같습니다. 선언하지 않으면 시스템은 애플리케이션의 최대 API 수준이 없다고 가정합니다. 시스템에서 속성을 처리하는 방법에 관한 자세한 내용은 이 속성의 설명을 참고하세요.

애플리케이션의 매니페스트에 선언한 경우 <uses-sdk> 요소는 다음과 같은 형태일 수 있습니다.

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

애플리케이션이 android:minSdkVersion에 API 수준을 선언하는 주된 이유는 지정된 API 수준에서 도입된 API를 사용한다는 것을 Android 시스템에 알리는 것입니다.

애플리케이션이 API 수준이 낮은 플랫폼에 설치되면 존재하지 않는 API에 액세스하려고 하면 런타임에 비정상 종료됩니다. 시스템은 가장 낮은 API 수준이 대상 기기의 플랫폼 버전보다 높은 경우 애플리케이션이 설치하지 못하게 하여 이러한 결과를 방지합니다.

개발 고려 사항

다음 섹션에서는 애플리케이션을 개발할 때 고려해야 하는 API 수준과 관련된 정보를 제공합니다.

애플리케이션의 향후 호환성

Android 애플리케이션은 일반적으로 Android 플랫폼의 새 버전과 호환됩니다.

프레임워크 API의 거의 모든 변경사항은 추가된 것이므로 특정 버전의 API를 사용하여 개발된 Android 애플리케이션은 API 수준에서 지정하는 대로 Android 플랫폼의 이후 버전 및 상위 API 수준과 호환됩니다. 어떤 이유로든 나중에 삭제된 API 요소를 애플리케이션에서 사용하는 격리된 경우를 제외하고 모든 이후 Android 플랫폼 버전에서 애플리케이션을 실행할 수 있습니다.

이후 버전과의 호환성은 대부분의 Android 기기가 무선 시스템 업데이트(OTA)를 수신하므로 중요합니다. 사용자는 애플리케이션을 설치하여 성공적으로 사용하고 나중에 새 Android 플랫폼 버전의 OTA 업데이트를 수신할 수 있습니다. 업데이트가 설치되면 애플리케이션은 새 런타임 버전의 환경에서 실행되지만, 이 런타임에는 애플리케이션이 사용하는 API 및 시스템 기능이 포함됩니다.

기본 시스템 자체의 변경사항과 같이 API를 아래에서 변경하면 새 환경에서 실행되는 애플리케이션에 영향을 미칠 수 있습니다. 애플리케이션 개발자는 애플리케이션이 각 시스템 환경에서 어떻게 표시되고 동작하는지 이해하는 것이 중요합니다.

다양한 Android 플랫폼 버전에서 애플리케이션을 테스트하는 데 도움이 되도록 Android SDK에는 다운로드할 수 있는 여러 플랫폼이 포함되어 있습니다. 각 플랫폼에는 애플리케이션을 테스트하기 위해 AVD에서 실행할 수 있는 호환되는 시스템 이미지가 포함되어 있습니다.

애플리케이션의 하위 호환성

Android 애플리케이션이 컴파일된 버전 이전의 Android 플랫폼 버전과 반드시 호환되는 것은 아닙니다.

각 새 Android 플랫폼 버전은 애플리케이션에 새 플랫폼 기능의 액세스 권한을 제공하거나 기존 API 요소를 대체하는 프레임워크 API와 같은 새 프레임워크 API를 포함할 수 있습니다. 새 API는 API 수준에서 지정된 대로 새 플랫폼에서 실행 중이거나 이후 버전의 플랫폼에서 실행될 때 애플리케이션에서 액세스할 수 있습니다. 하지만 이전 버전의 플랫폼에는 새 API가 포함되어 있지 않으므로 새 API를 사용하는 애플리케이션은 해당 플랫폼에서 실행할 수 없습니다.

Android 지원 기기는 플랫폼의 이전 버전으로 다운그레이드될 가능성이 없지만, 현장에 이전 플랫폼 버전을 실행하는 기기가 많을 수 있음을 인식하는 것이 중요합니다. 무선 업데이트를 수신하는 기기 중에서도 일부는 상당한 시간 동안 지연되고 업데이트를 수신하지 못할 수 있습니다.

플랫폼 버전 및 API 수준 선택

애플리케이션을 개발할 때 애플리케이션을 컴파일할 플랫폼 버전을 선택합니다. 일반적으로 애플리케이션이 지원할 수 있는 가장 낮은 플랫폼 버전에 대해 애플리케이션을 컴파일합니다.

연속 하위 빌드 타겟을 대상으로 애플리케이션을 컴파일하여 가능한 최소 플랫폼 버전을 결정할 수 있습니다. 가장 낮은 버전을 결정한 후 플랫폼 버전과 API 수준을 사용하여 AVD를 만들고 애플리케이션을 충분히 테스트합니다. 애플리케이션의 매니페스트에서 android:minSdkVersion 속성을 선언하고 값을 플랫폼 버전의 API 수준으로 설정해야 합니다.

최소 API 수준 선언

최신 플랫폼 버전에 도입된 시스템 기능 또는 API를 사용하는 애플리케이션을 빌드하는 경우 android:minSdkVersion 속성을 최신 플랫폼 버전의 API 수준으로 설정합니다. 기기가 호환되는 Android 플랫폼 버전을 실행하는 경우에만 사용자가 애플리케이션을 설치할 수 있도록 하기 위함입니다. 따라서 애플리케이션이 기기에서 제대로 작동할 수 있도록 합니다.

애플리케이션이 최신 플랫폼 버전에서 도입된 API를 사용하지만 android:minSdkVersion 속성을 선언하지 않은 경우 최신 버전의 플랫폼을 실행하는 기기에서는 제대로 실행되지만 이전 버전의 플랫폼을 실행하는 기기에서는 제대로 실행되지 않습니다. 후자의 경우 애플리케이션이 이전 버전에 없는 API를 사용하려고 하면 런타임에 비정상 종료됩니다.

더 높은 API 수준에서 테스트

애플리케이션을 컴파일한 후 애플리케이션의 android:minSdkVersion 속성에 지정된 플랫폼에서 테스트해야 합니다. 이렇게 하려면 애플리케이션이 필요로 하는 플랫폼 버전을 사용하는 AVD를 만들어야 합니다. 또한 이후 버전과의 호환성을 확인하려면 애플리케이션에서 사용하는 API 수준보다 높은 API 수준을 사용하는 모든 플랫폼에서 애플리케이션을 실행하고 테스트하세요.

Android SDK는 최신 버전을 비롯하여 사용할 수 있는 여러 플랫폼 버전을 포함하며 필요에 따라 다른 플랫폼 버전을 다운로드하는 데 사용할 수 있는 업데이터 도구를 제공합니다.

업데이트 프로그램에 액세스하려면 <sdk>/tools 디렉터리에 있는 android 명령줄 도구를 사용하세요. android sdk를 실행하여 SDK 업데이트 프로그램을 시작할 수 있습니다. android.bat (Windows) 또는 android (OS X/Linux) 파일을 더블클릭해도 됩니다.

에뮬레이터에서 여러 플랫폼 버전에 관해 애플리케이션을 실행하려면 테스트할 각 플랫폼 버전용 AVD를 생성합니다. AVD에 관한 자세한 내용은 가상 기기 만들기 및 관리를 참고하세요. 실제 기기를 테스트에 사용하는 경우 기기가 실행하는 Android 플랫폼의 API 수준을 알아야 합니다. 플랫폼 버전 및 API 수준 목록은 이 문서의 표를 참고하세요.

API 수준별로 참조 문서 필터링

Android 플랫폼 참조 문서 페이지는 각 페이지의 왼쪽 상단에 'API 수준' 컨트롤을 제공합니다. 이 컨트롤을 사용하면 매니페스트 파일의 android:minSdkVersion 속성에 지정된 API 수준에 따라 실제로 애플리케이션에서 액세스할 수 있는 API 부분에 관한 문서만 표시할 수 있습니다.

필터링을 사용하려면 메뉴에서 애플리케이션이 지정한 API 수준을 선택합니다. 이후 API 수준에 도입된 API는 애플리케이션이 액세스할 수 없으므로 비활성화되고 콘텐츠는 마스킹됩니다.

문서에서 API 수준별로 필터링해도 각 API 수준에 도입된 새로운 기능 또는 도입된 내용을 확인할 수는 없습니다. 지정된 API 수준과 연결된 전체 API를 보는 동시에 이후 API 수준에서 도입된 API 요소를 제외하는 방법을 제공합니다.

전체 문서 보기로 돌아가려면 API 수준 메뉴 맨 위에 있는 REL을 선택합니다. 기본적으로 API 수준 필터링은 API 수준에 관계없이 전체 프레임워크 API를 볼 수 있도록 사용 중지됩니다.

개별 API 요소에 관한 참조 문서는 각 요소가 도입된 API 수준을 지정합니다. 패키지 및 클래스의 API 수준은 각 문서 페이지의 콘텐츠 영역 오른쪽 상단에 'API 수준에 추가됨'으로 지정됩니다. 클래스 멤버의 API 수준은 오른쪽 여백의 세부 설명 헤더에 지정됩니다.