Skip to content

Most visited

Recently visited

navigation

<uses-sdk>

구문:
<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 레벨이 이 특성에 지정된 값보다 낮은 경우 사용자가 애플리케이션을 설치하는 것을 방지합니다. 항상 이 특성을 선언해야 합니다.

주의: 이 특성을 선언하지 않는 경우 시스템이 애플리케이션이 모든 Android 버전과 호환됨을 나타내는 기본값 "1"을 가정합니다. 애플리케이션이 모든 버전과 호환되지 않고(예를 들어, 애플리케이션이 API Level 3에서 도입된 API를 사용함) 적절한 minSdkVersion을 선언하지 않은 경우, API 레벨 3 미만의 시스템에 설치된 애플리케이션은 사용할 수 없는 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는 다음 요소로 구성되어 있습니다.

연속된 각 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 레벨버전 코드참고
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 레벨 식별자를 내부적으로 Android 시스템에 저장합니다.

애플리케이션은 프레임워크 API가 제공하는 매니페스트 요소 <uses-sdk>를 사용하여 지원하도록 고안된 기본 API 레벨뿐만 아니라 실행할 수 있는 최소 및 최대 API 레벨을 설명할 수 있습니다. 이 요소는 다음과 같은 3개의 주요 특성을 제공합니다.

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

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

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

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

애플리케이션이 android:minSdkVersion에 API 레벨을 선언하는 주요한 이유는 지정된 API 레벨에 도입된 API를 사용하고 있음을 Android 시스템에 알리는 것입니다. 애플리케이션이 더 낮은 API 레벨을 가진 플랫폼에 설치된 경우, 존재하지 않는 API에 액세스하려고 시도하면 런타임에 작동이 중단됩니다. 필요로 하는 최하위 API 레벨이 대상 기기의 플랫폼 버전의 API 레벨보다 높은 경우, 시스템은 애플리케이션의 설치를 불허하여 그러한 결과를 방지합니다.

예를 들어, android.appwidget 패키지는 API 레벨 3에서 도입되었습니다. 애플리케이션이 해당 API를 사용하는 경우 android:minSdkVersion 특성의 값을 "3"으로 선언해야 합니다. 그러면 애플리케이션은 Android 1.5(API 레벨 3) 및 Android 1.6(API 레벨 4)와 같은 플랫폼에 설치할 수 있지만, Android 1.1(API 레벨 2) 및 Android 1.0 플랫폼(API 레벨 1)에는 설치할 수 없습니다.

애플리케이션의 API 레벨 요구사항을 지정하는 방법에 대한 자세한 내용은 매니페스트 파일 문서의 <uses-sdk> 섹션을 참조하세요.

개발 고려 사항

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

애플리케이션의 이후 버전과의 호환성

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

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

이후 버전과의 호환성은 대부분의 Android 기기가 무선 시스템 업데이트를 수신하므로 중요합니다. 사용자가 애플리케이션을 설치하여 성공적으로 사용하고 나중에 새 Android 플랫폼 버전에 대한 무선 업데이트를 수신할 수 있습니다. 업데이트가 설치되면 애플리케이션이 의존하는 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 레벨보다 상위 레벨을 사용하는 모든 플랫폼에서 애플리케이션을 실행하고 테스트해야 합니다.

Android SDK는 최신 버전을 비롯하여 사용할 수 있는 다중 플랫폼 버전을 포함하고 있으며 필요한 경우 다른 플랫폼 버전을 다운로드하는 데 사용할 수 있는 업데이트 프로그램 도구를 제공합니다.

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

에뮬레이터에서 여러 플랫폼 버전에 대해 애플리케이션을 실행하려면 테스트할 각 플랫폼 버전에 대한 AVD를 생성합니다. AVD에 대한 자세한 내용은 가상 기기 생성 및 관리를 참조하세요. 테스트용 물리적 기기를 사용 중인 경우 기기가 실행하는 Android 플랫폼의 API 레벨을 알아야 합니다. 플랫폼 버전 및 해당 API 레벨의 목록은 이 문서의 위쪽에 있는 표를 참조하세요.

API 레벨별 참조 문서 필터링

Android 개발자 사이트의 참조 문서 페이지는 각 페이지의 오른쪽 위에 "Filter by API Level" 컨트롤을 제공합니다. 이 컨트롤을 사용하여 매니페스트 파일의 android:minSdkVersion 특성에 지정한 API 레벨에 따라 실제로 애플리케이션이 액세스할 수 있는 API 요소에 대한 문서만 표시할 수 있습니다.

필터링을 사용하려면 페이지 검색 상자 바로 아래에서 필터링을 활성화하는 체크박스를 선택합니다. 그리고 나서 "Filter by API Level" 컨트롤을 애플리케이션이 지정한 것과 동일한 API 레벨로 설정합니다. 이후 API 레벨에 도입된 API는 애플리케이션이 액세스할 수 없으므로 회색으로 표시되고 해당 콘텐츠는 마스킹됩니다.

문서에서 API 레벨별 필터링은 새롭거나 각 API 레벨에 도입된 항목의 뷰를 제공하지 않습니다. 단순히 지정된 API 레벨과 연결된 전체 API를 보는 방법만 제공하며 이후 API 레벨에 도입된 API 요소는 제외합니다.

API 문서를 필터링하지 않으려면 체크박스를 사용하여 기능을 비활성화하면 됩니다. 기본적으로 API 레벨 필터링은 API 레벨에 상관없이 전체 프레임워크 API를 볼 수 있도록 비활성화됩니다.

또한 개별 API 요소에 대한 참조 문서는 각 요소가 도입된 API 레벨을 지정합니다. 패키지 및 클래스에 대한 API 레벨은 각 문서 페이지 콘텐츠 영역의 오른쪽 위에서 "Since <api level>"로 지정됩니다. 클래스 멤버에 대한 API 레벨은 오른쪽 여백의 세부 설명 헤더에 지정됩니다.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)