SDK 확장 프로그램

SDK 확장 프로그램은 모듈식 시스템 구성요소를 사용하여 이전에 출시된 특정 API 수준의 공개 SDK에 API를 추가합니다. 이러한 API는 최종 사용자가 Google Play 시스템 업데이트를 통해 모듈 업데이트를 수신할 때 기기에 제공됩니다. 앱 개발자는 앱에서 이러한 API를 사용하여 이전 Android 버전의 SDK에서 사용할 수 없었던 추가 기능을 제공할 수 있습니다.

API 버전 관리

Android 11(API 수준 30)부터 Android 기기가 SDK 확장 프로그램 세트를 포함하게 되었습니다. 새 API가 추가되면 API 수준에 포함되며, 특정 버전의 SDK 확장 프로그램에도 포함될 수 있습니다. 예를 들어 사진 선택 도구의 ACTION_PICK_IMAGES API는 Android 13(API 수준 33)의 공개 SDK에 추가되었으며, R 확장 프로그램 버전 2부터 SDK 확장 프로그램을 통해서도 사용할 수 있습니다. SDK 확장 프로그램 이름은 정수 상수(Build.VERSION_CODES의 상수 또는 SdkExtensions 클래스에 정의된 상수, 예: SdkExtensions.AD_SERVICES)에 대응됩니다.

사용할 SDK 확장 프로그램 확인하기

SDK 확장 프로그램 API를 사용하려면 먼저 어느 SDK에 앱의 사용 사례를 지원하는 API가 포함되어 있는지 확인해야 합니다.

SDK 확장 프로그램 API용 API 참조 페이지에는 앱이 API에 액세스하는 데 사용할 수 있는 가장 오래된 SDK 확장 프로그램 버전이 나와 있습니다. 문서에 (API 수준에 의해 참조된) Android 플랫폼 버전도 나와 있다면 이 API는 이 버전 또는 이후 버전의 Android를 실행하는 모든 기기에서 사용할 수도 있습니다.

예를 들어 ACTION_PICK_IMAGES는 Android 13(API 수준 33)부터 공개 SDK에서 사용할 수 있으며, 기기에 R 확장 프로그램 2 및 이후 버전이 설치되어 있는 경우 가장 이르게는 Android 11(API 수준 30)이 설치된 기기에서도 사용할 수 있습니다.

SDK 확장 프로그램에 포함된 API는 API 참조 문서에 확장 프로그램의 버전이 표시되어 있음

이 API를 사용하려면 API 수준 33 이상 또는 확장 프로그램 수준 2 이상인 SDK를 기준으로 컴파일해야 합니다.

확장 프로그램 SDK를 사용하려면 다음 단계를 따르세요.

  1. 기능 문서와 사용하려는 API의 API 참조에서 필요한 최소 확장 프로그램 버전을 찾습니다.
  2. 기능 세트에 필요한 확장 프로그램 버전을 확인했으면 Android 스튜디오에서 SDK Manager를 엽니다.
  3. 해당하는 확장 프로그램 버전(API는 가산성이므로 그보다 높은 버전도 가능)에 대응되는 Android SDK 플랫폼 항목을 선택합니다. 예: Android SDK 플랫폼 33, 확장 프로그램 수준 4.

  4. 앱의 build.gradle.kts 또는 build.gradle 파일에서 값을 선언합니다.

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

    android {
    compileSdk = 33
    compileSdkExtension = 4
    ...
}

SDK 확장 프로그램을 사용할 수 있는지 확인하기

앱은 어느 SDK 확장 프로그램 버전을 사용할 수 있는지 런타임에 확인할 수 있으며, 개발자는 이어지는 섹션에서 설명하는 바와 같이 개발 중에 Android 디버그 브리지(adb) 명령어를 사용하여 확장 프로그램 버전을 찾아볼 수 있습니다.

런타임에 확인하기

앱은 런타임에 getExtensionVersion() 메서드를 사용하여 주어진 플랫폼 버전에서 SDK 확장 프로그램을 사용할 수 있는지 확인할 수 있습니다. 예를 들어 다음 코드는 Android 11(API 수준 30) SDK 확장 프로그램의 확장 프로그램 버전 2 이상을 사용할 수 있는지 확인합니다.

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

Java

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

이는 Build.VERSION.SDK_INT 기반으로 검사하는 것과 비슷합니다.

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

Java

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

이 SDK_INT 검사는 여전히 안전하고 유효하지만 isPhotoPickerAvailable은 확장 프로그램 API를 사용할 수 있더라도 일부 기기에서 false를 반환합니다. 따라서 SDK_INT 검사는 최적이 아니며, 확장 프로그램 버전 검사는 API 사용 가능 여부를 확인하는 더 나은 방법입니다. SDK_INT가 33 이상(Android 13 및 이후 버전)인 모든 기기는 공개 SDK에 사진 선택 도구 API가 있지만, SDK_INT가 33 미만인 기기(예: Android 11, 12, 12L) 역시도 R 확장 프로그램 버전이 2 이상이라면 API에 액세스할 수 있습니다.

이 경우 확장 프로그램 버전 검사를 사용하면 앱이 더 많은 사용자에게 추가 기능을 제공하도록 할 수 있습니다. 기기에서 특정 SDK 확장 프로그램을 검사하는 데 사용할 수 있는 모든 상수의 목록은 SDK 확장 프로그램 이름 및 상수를 참고하세요.

광고 서비스 확장 프로그램

AdServices API 참조는 일반적인 SDK 확장 프로그램과 마찬가지로 특정 API가 '광고 서비스 확장 프로그램' 버전의 일부임을 나타냅니다. 광고 서비스 확장 프로그램은 일반적인 SDK 확장 프로그램과 달리 SdkExtensions.AD_SERVICES 상수를 사용하여 기기에 어느 버전이 있는지 확인합니다.

Kotlin

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

광고 서비스 확장 프로그램의 기능과 시작하는 방법을 자세히 알아보려면 광고 서비스 광고 확장 프로그램 문서를 참고하세요.

유틸리티 메서드

SDK 확장 프로그램에 SDK 확장 프로그램 API의 사용 가능 여부를 확인하는 Jetpack 유틸리티 메서드가 있는 경우가 있습니다. 예를 들어 조건부 버전 검사를 추상화하는 Jetpack 라이브러리 함수를 사용하여 PhotoPicker 사용 가능 여부를 확인할 수 있습니다.

도구 지원

Android 스튜디오 Flamingo | 2022.2.1 및 이후 버전에서는 린트 도구가 NewAPI 검사의 일부로 SDK 확장 프로그램 버전 문제를 검사할 수 있습니다. 이에 더해 Android 스튜디오는 SDK 확장 프로그램을 사용하여 실행된 API의 올바른 버전 검사를 자동으로 생성할 수 있습니다.

린트 도구는 API를 호출하는 데 필요한 최소 SDK 확장 프로그램 버전이 충족되지 않은 인스턴스를 플래그합니다.

SDK 확장 프로그램 이름 및 상수

다음 표에서는 API 참조 문서에 나열된 여러 SDK 확장 프로그램이 앱에서 런타임에 API 사용 가능 여부를 확인하는 데 사용할 수 있는 상수에 어떻게 매핑되는지 설명합니다. 각 공개 SDK의 일반적인 SDK 확장 프로그램이 Build.VERSION_CODES 값에 매핑됩니다.

SDK 확장 프로그램 이름 상수 대상 기기
R 확장 프로그램 VERSION_CODES.R Android 11(API 수준 30) 및 이후 버전
S 확장 프로그램 VERSION_CODES.S Android 12(API 수준 31) 및 이후 버전
T 확장 프로그램 VERSION_CODES.TIRAMISU Android 13(API 수준 33) 및 이후 버전
광고 서비스 확장 프로그램 SdkExtensions.AD_SERVICES Android 13(API 수준 33) 및 이후 버전

adb를 사용하여 확인

adb를 사용하여 기기에서 어느 SDK 확장 프로그램을 사용할 수 있는지 확인하려면 다음 명령어를 실행합니다.

adb shell getprop | grep build.version.extensions

명령어를 실행하면 다음과 비슷한 출력이 표시됩니다.

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

각 행에는 기기에 있는 SDK 확장 프로그램과 확장 프로그램 버전(여기서는 3)이 표시됩니다.