다음을 통해 공유

Android API 수준 이해

  • 아티클

Xamarin.Android에는 여러 버전의 Android와 앱의 호환성을 결정하는 여러 Android API 수준 설정이 있습니다. 이 가이드에서는 이러한 설정의 의미, 구성 방법 및 런타임에 앱에 미치는 영향에 대해 설명합니다.

빠른 시작

Xamarin.Android는 다음 세 가지 Android API 수준 프로젝트 설정을 노출합니다.

  • 대상 프레임워크 – 애플리케이션을 빌드하는 데 사용할 프레임워크를 지정합니다. 이 API 수준은 컴파일 시간에 Xamarin.Android에서 사용됩니다.

  • 최소 Android 버전 – 앱에서 지원하려는 가장 오래된 Android 버전을 지정합니다. 이 API 수준은 런타임에 Android에서 사용됩니다.

  • 대상 Android 버전 – 앱이 실행되도록 의도된 Android 버전을 지정합니다. 이 API 수준은 런타임에 Android에서 사용됩니다.

프로젝트에 대한 API 수준을 구성하려면 먼저 해당 API 수준에 대한 SDK 플랫폼 구성 요소를 설치해야 합니다. Android SDK 구성 요소 다운로드 및 설치에 대한 자세한 내용은 Android SDK 설치 프로그램을 참조 하세요.

참고 항목

2021년 8월부터 Google Play 콘솔에서는 새 앱이 API 수준 30(Android 11.0) 이상을 대상으로 해야 합니다. 기존 앱은 2021년 11월부터 API 수준 30 이상을 대상으로 해야 합니다. 자세한 내용은 Play 콘솔 설명서의 "앱 만들기 및 설정"에서 Play 콘솔 에 대한 대상 API 수준 요구 사항을 참조하세요.

일반적으로 세 Xamarin.Android API 수준은 모두 동일한 값으로 설정됩니다. 애플리케이션 페이지에서 Android 버전(대상 프레임워크)을 사용하여 컴파일을 안정적인 최신 API 버전(또는 최소한 필요한 모든 기능이 있는 Android 버전)으로 설정합니다. 다음 스크린샷에서 대상 프레임워크는 Android 7.1(API 수준 25 - Nougat)으로 설정됩니다.

Target Framework version defaults to Compile using Android version

Android 매니페스트 페이지에서 SDK 버전을 사용하여 컴파일을 사용하도록 최소 Android 버전을 설정하고 대상 Android 버전을 대상 프레임워크 버전과 동일한 값으로 설정합니다(다음 스크린샷에서 대상 Android Framework는 Android 7.1(Nougat)로 설정됨).

Minimum and Target Android versions set to Target Framework version

이전 버전의 Android와 기본 호환성을 유지하려면 최소 Android 버전을 앱에서 지원하려는 가장 오래된 Android 버전을 대상으로 설정합니다. (API 수준 14는 필요한 최소 API 수준입니다.Google Play 서비스 및 Firebase 지원.) 다음 예제 구성은 API 수준 14부터 API 수준 25까지 Android 버전을 지원합니다.

Compile using API level 25 Nougat, Minimum Android version set to API level 14

앱이 여러 Android 버전을 지원하는 경우 앱이 최소 Android 버전 설정과 함께 작동하는지 확인하기 위해 코드에 런타임 검사 포함되어야 합니다(자세한 내용은 아래 Android 버전에 대한 런타임 검사 참조). 라이브러리를 사용하거나 만드는 경우 라이브러리에 대한 API 수준 설정을 구성하는 모범 사례는 아래의 API 수준 및 라이브러리를 참조하세요.

Android 버전 및 API 수준

Android 플랫폼이 발전하고 새 Android 버전이 릴리스됨에 따라 각 Android 버전에는 API 수준이라는 고유한 정수 식별자가 할당됩니다. 따라서 각 Android 버전은 단일 Android API 수준에 해당합니다. 사용자가 이전 버전과 최신 버전의 Android에 앱을 설치하기 때문에 실제 Android 앱은 여러 Android API 수준에서 작동하도록 설계되어야 합니다.

Android 버전

Android의 각 릴리스는 다음과 같은 여러 이름으로 진행됩니다.

  • Android 9.0과 같은 Android 버전
  • 코드(또는 디저트) 이름(예: Pie)
  • API 수준 28과 같은 해당 API 수준

Android 코드 이름은 아래 표와 같이 여러 버전 및 API 수준에 해당할 수 있지만 각 Android 버전은 정확히 하나의 API 수준에 해당합니다.

또한 Xamarin.Android는 현재 알려진 Android API 수준에 매핑되는 빌드 버전 코드를 정의합니다. 다음 표는 API 수준, Android 버전, 코드 이름 및 Xamarin.Android 빌드 버전 코드 간에 변환하는 데 도움이 됩니다(빌드 버전 코드는 네임스페이 Android.OS 스에 정의됨).

속성 버전 API 수준 릴리스됨 빌드 버전 코드
Q 10.0 29 2020년 8월 BuildVersionCodes.Q
Pie 9.0 28 2018년 8월 BuildVersionCodes.P
Oreo 8.1 27 2017년 12월 BuildVersionCodes.OMr1
Oreo 8.0 26 Aug 2017 BuildVersionCodes.O
Nougat 7.1 25 2016년 12월 BuildVersionCodes.NMr1
Nougat 7.0 24 2016년 8월 BuildVersionCodes.N
Marshmallow 6.0 23 2015년 8월 BuildVersionCodes.M
Lollipop 5.1 22 2015년 3월 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 2014년 11월 BuildVersionCodes.Lollipop
Kitkat Watch 4.4W 20 Jun 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 2013년 10월 BuildVersionCodes.KitKat
젤리 4.3 18 Jul 2013 BuildVersionCodes.JellyBeanMr2
젤리 4.2-4.2.2 17 2012년 11월 BuildVersionCodes.JellyBeanMr1
젤리 4.1-4.1.1 16 2012년 6월 BuildVersionCodes.JellyBean
Ice Cream Sandwich 4.0.3-4.0.4 15 2011년 12월 BuildVersionCodes.IceCreamSandwichMr1
Ice Cream Sandwich 4.0-4.0.2 14 2011년 10월 BuildVersionCodes.IceCreamSandwich
Honeycomb 3.2 13 2011년 6월 BuildVersionCodes.HoneyCombMr2
Honeycomb 3.1.x 12 2011년 5월 BuildVersionCodes.HoneyCombMr1
Honeycomb 3.0.x 11 2011년 2월 BuildVersionCodes.HoneyComb
진저 2.3.3-2.3.4 10 2011년 2월 BuildVersionCodes.GingerBreadMr1
진저 2.3-2.3.2 9 2010년 11월 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 2010년 6월 BuildVersionCodes.Froyo
에클레어(Eclair) 2.1.x 7 2010년 1월 BuildVersionCodes.EclairMr1
에클레어(Eclair) 2.0.1 6 2009년 12월 BuildVersionCodes.Eclair01
에클레어(Eclair) 2.0 5 2009년 11월 BuildVersionCodes.Eclair
도넛 1.6 4 2009년 9월 BuildVersionCodes.Donut
컵 케 익 1.5 3 2009년 5월 BuildVersionCodes.Cupcake
Base 1.1 2 2009년 2월 BuildVersionCodes.Base11
Base 1.0 1 2008년 10월 BuildVersionCodes.Base

이 표에서 설명한 것처럼 새 Android 버전은 자주 릴리스되며 때로는 연간 두 개 이상의 릴리스가 있습니다. 따라서 앱을 실행할 수 있는 Android 디바이스의 우주에는 다양한 이전 및 최신 Android 버전이 포함됩니다. 앱이 다양한 버전의 Android에서 일관되고 안정적으로 실행되도록 보장하려면 어떻게 해야 할까요? Android의 API 수준은 이 문제를 관리하는 데 도움이 될 수 있습니다.

Android API 수준

각 Android 디바이스는 정확히 하나의 API 수준에서 실행됩니다. 이 API 수준은 Android 플랫폼 버전별로 고유하도록 보장됩니다. API 수준은 앱이 호출할 수 있는 API 집합의 버전을 정확하게 식별합니다. 개발자로 코딩하는 매니페스트 요소, 권한 등의 조합을 식별합니다. Android의 API 수준 시스템은 디바이스에 애플리케이션을 설치하기 전에 애플리케이션이 Android 시스템 이미지와 호환되는지 여부를 결정하는 데 도움이 됩니다.

애플리케이션이 빌드되면 다음 API 수준 정보가 포함됩니다.

  • 앱이 실행되도록 빌드된 Android의 대상 API 수준입니다.

  • Android 디바이스에서 앱을 실행해야 하는 최소 Android API 수준입니다.

이러한 설정은 앱을 올바르게 실행하는 데 필요한 기능을 설치 시 Android 디바이스에서 사용할 수 있도록 하는 데 사용됩니다. 그렇지 않은 경우 앱이 해당 디바이스에서 실행되지 않도록 차단됩니다. 예를 들어 Android 디바이스의 API 수준이 앱에 대해 지정한 최소 API 수준보다 낮은 경우 Android 디바이스는 사용자가 앱을 설치하지 못하게 합니다.

프로젝트 API 수준 설정

다음 섹션에서는 SDK Manager를 사용하여 대상으로 지정하려는 API 수준에 대한 개발 환경을 준비하는 방법과 Xamarin.Android에서 대상 프레임워크, 최소 Android 버전 및 대상 Android 버전 설정을 구성하는 방법에 대한 자세한 설명을 설명합니다.

Android SDK 플랫폼

Xamarin.Android에서 대상 또는 최소 API 수준을 선택하려면 먼저 해당 API 수준에 해당하는 Android SDK 플랫폼 버전을 설치해야 합니다. 대상 프레임워크, 최소 Android 버전 및 대상 Android 버전에 사용할 수 있는 옵션 범위는 설치한 Android SDK 버전 범위로 제한됩니다. SDK Manager를 사용하여 필요한 Android SDK 버전이 설치되어 있는지 확인하고 이를 사용하여 앱에 필요한 새 API 수준을 추가할 수 있습니다. API 수준을 설치하는 방법을 잘 모르는 경우 Android SDK 설치 프로그램을 참조 하세요.

대상 프레임워크

대상 프레임워크(라고도 함compileSdkVersion)는 빌드 시 앱이 컴파일되는 특정 Android 프레임워크 버전(API 수준)입니다. 이 설정은 앱 이 실행될 때 사용해야 하는 API를 지정하지만, 앱이 설치될 때 실제로 사용할 수 있는 API에는 영향을 주지 않습니다. 따라서 대상 프레임워크 설정을 변경해도 런타임 동작은 변경되지 않습니다.

대상 프레임워크는 애플리케이션이 연결된 라이브러리 버전을 식별합니다. 이 설정은 앱에서 사용할 수 있는 API를 결정합니다. 예를 들어 Android 5.0 Lollipop에서 도입된 NotificationBuilder.SetCategory 메서드를 사용하려면 대상 프레임워크를 API 수준 21(Lollipop) 이상으로 설정해야 합니다. 프로젝트의 대상 프레임워크를 API 수준(KitKat)과 같은 API 수준으로 설정하고 코드에서 메서드를 SetCategory 호출하려고 하면 컴파일 오류가 발생합니다.

항상 사용 가능한 최신 대상 프레임워크 버전으로 컴파일하는 것이 좋습니다. 이렇게 하면 코드에서 호출할 수 있는 사용되지 않는 API에 대한 유용한 경고 메시지가 제공됩니다. 최신 지원 라이브러리 릴리스를 사용하는 경우 최신 대상 프레임워크 버전을 사용하는 것이 특히 중요합니다. 각 라이브러리는 해당 지원 라이브러리의 최소 API 수준에서 앱이 컴파일될 것으로 예상합니다.

Visual Studio에서 대상 프레임워크 설정에 액세스하려면 솔루션 탐색기 프로젝트 속성을 열고 애플리케이션 페이지를 선택합니다.

Application page of project Properties

위와 같이 Android 버전을 사용하여 컴파일 아래의 드롭다운 메뉴에서 API 수준을 선택하여 대상 프레임워크를 설정합니다.

최소 Android 버전

최소 Android 버전(라고도 함minSdkVersion)은 애플리케이션을 설치하고 실행할 수 있는 가장 오래된 버전의 Android OS(즉, 가장 낮은 API 수준)입니다. 기본적으로 앱은 대상 프레임워크 설정 이상과 일치하는 디바이스에만 설치할 수 있습니다. 최소 Android 버전 설정이 대상 프레임워크 설정보다 낮 으면 이전 버전의 Android에서도 앱을 실행할 수 있습니다. 예를 들어 대상 프레임워크 를 Android 7.1(Nougat) 로 설정하고 최소 Android 버전을 Android 4.0.3(아이스크림 샌드위치)으로 설정하는 경우 앱을 API 수준 15에서 API 수준 25까지 모든 플랫폼에 설치할 수 있습니다.

앱이 이 플랫폼 범위에 성공적으로 빌드 및 설치될 수 있지만 이러한 모든 플랫폼에서 앱이 성공적으로 실행 된다는 보장은 아닙니다. 예를 들어 앱이 Android 5.0(Lollipop)에 설치되어 있고 코드가 Android 7.1(Nougat) 이상에서만 사용할 수 있는 API를 호출하는 경우 앱에 런타임 오류가 발생하여 충돌이 발생할 수 있습니다. 따라서 코드는 런타임에 실행 중인 Android 디바이스에서 지원하는 API만 호출하도록 해야 합니다. 즉, 앱이 최신 디바이스에서만 최신 API를 사용하도록 하려면 코드에 명시적 런타임 검사 포함되어야 합니다. 이 가이드의 뒷부분에 있는 Android 버전에 대한 런타임 검사는 이러한 런타임 검사 코드에 추가하는 방법을 설명합니다.

Visual Studio에서 최소 Android 버전 설정에 액세스하려면 솔루션 탐색기 프로젝트 속성을 열고 Android 매니페스트 페이지를 선택합니다. 최소 Android 버전 아래의 드롭다운 메뉴에서 애플리케이션에 대한 최소 Android 버전을 선택할 수 있습니다.

Minimum Android to target option set to Compile using SDK version

SDK 버전을 사용하여 컴파일 사용을 선택하는 경우 최소 Android 버전은 대상 프레임워크 설정과 동일합니다.

대상 Android 버전

대상 Android 버전(라고도 함targetSdkVersion)은 앱이 실행해야 하는 Android 디바이스의 API 수준입니다. Android는 이 설정을 사용하여 호환성 동작을 사용하도록 설정할지 여부를 결정합니다. 이렇게 하면 앱이 예상대로 계속 작동합니다. Android는 앱의 대상 Android 버전 설정을 사용하여 앱에 적용할 수 있는 동작 변경을 중단하지 않고 파악합니다(Android가 앞으로 호환성을 제공하는 방법입니다).

대상 프레임워크와 대상 Android 버전은 이름이 매우 비슷하지만 동일한 것은 아닙니다. 대상 프레임워크 설정은 컴파일 시간에 사용하기 위해 Xamarin.Android에 대상 API 수준 정보를 전달하고, 대상 Android 버전은 런타임에 사용할 대상 API 수준 정보를 Android에 전달합니다(앱이 설치되어 디바이스에서 실행 중일 때).

Visual Studio에서 이 설정에 액세스하려면 솔루션 탐색기 프로젝트 속성을 열고 Android 매니페스트 페이지를 선택합니다. 대상 Android 버전 아래의 드롭다운 메뉴에서 애플리케이션의 대상 Android 버전을 선택할 수 있습니다.

Target Android version set to Compile using SDK version

대상 Android 버전을 앱을 테스트하는 데 사용하는 최신 버전의 Android로 명시적으로 설정하는 것이 좋습니다. 이상적으로는 최신 Android SDK 버전으로 설정해야 합니다. 이렇게 하면 동작 변경을 진행하기 전에 새 API를 사용할 수 있습니다. 대부분의 개발자는 SDK 버전을 사용하여 컴파일을 사용하도록 대상 Android 버전을 설정하지 않는 것이 좋습니다.

일반적으로 대상 Android 버전은 최소 Android 버전 및 대상 프레임워크에 의해 경계되어야 합니다. 구체적인 요건은 다음과 같습니다.

최소 Android 버전 <= 대상 Android 버전 <= 대상 프레임워크

SDK 수준에 대한 자세한 내용은 Android Developer uses-sdk 설명서를 참조하세요.

Android 버전용 런타임 검사

Android의 새 버전이 출시될 때마다 프레임워크 API가 업데이트되어 새 기능 또는 대체 기능을 제공합니다. 몇 가지 예외를 제외하고 이전 Android 버전의 API 기능은 수정 없이 최신 Android 버전으로 전달됩니다. 따라서 앱이 특정 Android API 수준에서 실행되는 경우 일반적으로 수정 없이 이후 Android API 수준에서 실행할 수 있습니다. 하지만 이전 버전의 Android에서도 앱을 실행하려면 어떻게 해야 할까요?

대상 프레임워크 설정보다 낮은 최소 Android 버전을 선택하는 경우 런타임에 일부 API를 앱에서 사용할 수 없을 수 있습니다. 그러나 앱은 이전 디바이스에서 계속 실행할 수 있지만 기능이 줄어듭니다. 최소 Android 버전 설정에 해당하는 Android 플랫폼에서 사용할 수 없는 각 API에 대해 코드는 속성 값을 Android.OS.Build.VERSION.SdkInt 명시적으로 검사 앱이 실행 중인 플랫폼의 API 수준을 결정해야 합니다. API 수준이 호출하려는 API를 지원하는 최소 Android 버전보다 낮은 경우 코드는 이 API 호출을 수행하지 않고 제대로 작동하는 방법을 찾아야 합니다.

예를 들어 Android 5.0 Lollipop(이상)에서 실행할 때 NotificationBuilder.SetCategory 메서드를 사용하여 알림을 분류하려고 하지만 Android 4.1 Jelly Bean(사용할 수 없는 경우SetCategory)과 같은 이전 버전의 Android에서 앱을 실행하려고 한다고 가정해 보겠습니다. 이 가이드의 시작 부분에 있는 Android 버전 테이블을 참조하면 Android 5.0 Lollipop에 대한 빌드 버전 코드가 Android.OS.BuildVersionCodes.Lollipop표시됩니다. 사용할 수 없는 이전 버전의 Android SetCategory 를 지원하기 위해 코드는 런타임에 API 수준을 검색하고 API 수준이 Lollipop 빌드 버전 코드보다 크거나 같은 경우에만 조건부로 호출 SetCategory 할 수 있습니다.

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

이 예제에서 앱의 대상 프레임워크는 Android 5.0(API 수준 21)으로 설정되고 최소 Android 버전은 Android 4.1(API 수준 16)로 설정됩니다. API 수준 이상에서 사용할 수 있으므로 SetCategory 이 예제 코드는 실제로 사용할 수 있는 경우에만 호출 SetCategory 됩니다. API 수준이 16, 17, 18, 19 또는 20일 때 호출 SetCategory 을 시도하지 않습니다.Android.OS.BuildVersionCodes.Lollipop 이러한 이전 Android 버전에서는 알림이 제대로 정렬되지 않는 범위(유형별로 분류되지 않으므로)까지만 기능이 감소하지만 알림은 사용자에게 경고하기 위해 계속 게시됩니다. 앱은 여전히 작동하지만 해당 기능은 약간 줄어듭니다.

일반적으로 빌드 버전 검사 코드가 런타임 시 새로운 방식과 이전 방식 간에 결정하는 데 도움이 됩니다. 예시:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

하나 이상의 API가 없는 이전 Android 버전에서 실행되는 경우 앱의 기능을 줄이거나 수정하는 방법을 설명하는 빠르고 간단한 규칙은 없습니다. 위의 예제와 같은 SetCategory 일부 경우에는 API 호출을 사용할 수 없을 때 생략하는 것으로 충분합니다. 그러나 다른 경우에는 앱이 최적의 환경을 제공해야 하는 API 수준보다 작도록 검색되는 경우에 Android.OS.Build.VERSION.SdkInt 대한 대체 기능을 구현해야 할 수 있습니다.

API 수준 및 라이브러리

Xamarin.Android 라이브러리 프로젝트(예: 클래스 라이브러리 또는 바인딩 라이브러리)를 만들 때 대상 프레임워크 설정만 구성할 수 있습니다. 최소 Android 버전 및 대상 Android 버전 설정을 사용할 수 없습니다. Android 매니페스트 페이지가 없기 때문입니다.

Only the Compile using Android version option is available

결과 라이브러리는 독립 실행형 앱이 아니므로 최소 Android 버전 및 대상 Android 버전 설정을 사용할 수 없습니다. 라이브러리는 패키지된 앱에 따라 모든 Android 버전에서 실행될 수 있습니다. 라이브러리를 컴파일하는 방법을 지정할 수 있지만 라이브러리가 실행될 플랫폼 API 수준을 예측할 수는 없습니다. 이 점을 염두에 두고 라이브러리를 사용하거나 만들 때 다음 모범 사례를 확인해야 합니다.

  • Android 라이브러리를 사용할 때 – 애플리케이션에서 Android 라이브러리를 사용하는 경우 앱의 대상 프레임워크 설정을 라이브러리의 대상 프레임워크 설정만큼 높은 API 수준으로 설정해야 합니다.

  • Android 라이브러리 를 만들 때 – 다른 애플리케이션에서 사용할 Android 라이브러리를 만드는 경우 해당 대상 프레임워크 설정을 컴파일하기 위해 필요한 최소 API 수준으로 설정해야 합니다.

이러한 모범 사례는 라이브러리가 런타임에 사용할 수 없는 API를 호출하려고 시도하는 상황을 방지하는 데 권장됩니다(앱이 충돌할 수 있음). 라이브러리 개발자인 경우 API 호출의 사용을 총 API 노출 영역의 작고 잘 설정된 하위 집합으로 제한해야 합니다. 이렇게 하면 광범위한 Android 버전에서 라이브러리를 안전하게 사용할 수 있습니다.

요약

이 가이드에서는 Android API 수준을 사용하여 다양한 버전의 Android에서 앱 호환성을 관리하는 방법을 설명했습니다. Xamarin.Android 대상 프레임워크, 최소 Android 버전 및 대상 Android 버전 프로젝트 설정을 구성하기 위한 자세한 단계를 제공했습니다. Android SDK Manager를 사용하여 SDK 패키지를 설치하기 위한 지침을 제공하고, 런타임에 다양한 API 수준을 처리하는 코드를 작성하는 방법의 예제를 제공했으며, Android 라이브러리를 만들거나 사용할 때 API 수준을 관리하는 방법을 설명했습니다. 또한 API 수준을 Android 버전 번호(예: Android 4.4), Android 버전 이름(예: Kitkat) 및 Xamarin.Android 빌드 버전 코드와 관련된 포괄적인 목록을 제공했습니다.