<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 버전과 호환됨을 나타냅니다. 아니요이고 적절한 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 수준이 지정되어 있습니다. 각 버전을 실행 중인 기기의 관련 번호는 배포 대시보드를 참고하세요.

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 수준으로 지정한) API 버전을 사용하여 개발한 Android 애플리케이션은 Android 플랫폼의 이후 버전 및 상위 API 수준과 호환됩니다. 애플리케이션이 어떤 이유로 나중에 삭제된 API 요소를 사용하는 별도의 경우를 제외하고 모든 이후 Android 플랫폼 버전에서 애플리케이션을 실행할 수 있습니다.

이후 버전과의 호환성은 대부분의 Android 기기가 무선 시스템 업데이트(OTA)를 수신하므로 중요합니다. 사용자가 애플리케이션을 설치하여 성공적으로 사용하고 나중에 새 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 플랫폼 참조 문서는 각 페이지의 왼쪽 상단에 'API 수준' 컨트롤이 나와 있습니다. 이 컨트롤을 사용하여 매니페스트 파일의 android:minSdkVersion 속성에 지정한 API 수준에 따라 실제로 애플리케이션이 액세스할 수 있는 API 요소의 문서만 표시할 수 있습니다.

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

문서에서 API 수준별로 필터링해도 새로운 항목이나 각 API 수준에 도입된 항목을 볼 수 있는 것은 아닙니다. 특정 API 수준과 관련된 전체 API를 볼 수 있는 방법을 제공하며, 이후 API 수준에서 도입된 API 요소는 제외됩니다.

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

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