이 페이지는 Cloud Translation API를 통해 번역되었습니다.

호환성 프레임워크 도구

Android 11에서는 Android 플랫폼 최신 버전의 동작 변경사항과 관련해 앱을 테스트하고 디버그하기 위한 새로운 개발자 도구가 도입되었습니다. 이러한 도구는 호환성 프레임워크의 일환으로, 앱 개발자가 개발자 옵션 또는 ADB를 사용하여 브레이킹 체인지를 개별적으로 사용 설정하거나 중지하도록 해 줍니다. 안정적인 최신 API 버전을 타겟팅하기 위해 앱을 준비하거나 다음 Android 버전의 미리보기 출시로 앱을 테스트할 때 이러한 유연성을 활용해 보세요.

호환성 프레임워크 도구를 사용할 경우, Android 플랫폼은 내부 로직을 자동으로 조정하므로 기본 테스트를 실행하기 위해 targetSDKVersion을 변경하거나 앱을 다시 컴파일할 필요가 없습니다. 변경사항을 개별적으로 사용 설정하거나 중지할 수 있으므로 동작 변경사항을 한 번에 하나씩 격리, 테스트, 디버그하거나 다른 항목을 먼저 테스트해야 하는 경우 문제를 일으키는 단일 변경사항을 사용 중지할 수 있습니다.

사용 설정된 변경사항을 확인하는 방법

동작 변경사항을 사용 설정하면 그러한 변경사항의 영향을 받는 플랫폼 API에 대한 앱의 액세스 방식이 달라질 수 있습니다. 개발자 옵션, logcat 또는 ADB 명령어를 사용하여 사용 설정된 동작 변경사항을 확인할 수 있습니다.

개발자 옵션을 사용하여 사용 설정된 변경사항 확인

그림 1. 개발자 옵션의 앱 호환성 변경사항 화면

기기의 개발자 옵션에서 사용 설정된 변경사항을 확인하고 변경사항을 사용 설정하거나 사용 중지할 수 있습니다. 이 옵션에 액세스하려면 다음 단계를 따르세요.

개발자 옵션이 아직 사용 설정되지 않았다면 개발자 옵션을 사용 설정합니다.
기기의 설정 앱을 열고 시스템 > 고급 > 개발자 옵션 > 앱 호환성 변경사항으로 이동합니다.
목록에서 앱을 선택합니다.

참고: 변경사항을 사용 설정하거나 사용 중지하려면 앱의 디버그 가능 빌드 변형을 사용해야 합니다.

각 동작 변경사항은 대체로 다음 두 카테고리 중 하나에 속합니다.

앱의 targetSdkVersion에 관계없이 변경된 버전의 Android에서 실행되는 모든 앱에 영향을 주는 변경사항:

이러한 변경사항은 호환성 프레임워크에서 기본적으로 사용 설정되며 UI의 기본적으로 사용 설정된 앱의 변경사항 섹션에 나열됩니다.
특정 Android 버전을 타겟팅하는 앱에만 영향을 미치는 변경사항: 이러한 변경사항은 특정 버전의 Android를 타겟팅하는 앱에만 영향을 주기 때문에 targetSDKVersion으로 관리되는 변경사항이라고도 합니다.

이러한 변경사항은 앱이 표시된 API 버전보다 높은 버전을 타겟팅한다면 호환성 프레임워크에서 기본적으로 사용 설정됩니다. 예를 들어, Android 13 (API 수준 33)에서 targetSDKVersion으로 관리되었던 동작 변경사항은 targetSdkVersion 33 이상 사용 설정됨이라는 제목의 섹션의 UI에 표시됩니다. 일부 이전 버전의 Android에서는 이 섹션의 제목이 'SDK API_LEVEL 이후 사용 설정됨'으로 표시됩니다.

참고: API 수준이 최종 결정될 때까지 Android 15 미리보기 기간에는 Android 15를 타겟팅할 때만 사용 설정되는 일부 변경사항이 최종 가정 API 수준인 35 대신 API 수준에 10000 값을 사용합니다.

그림 1에 기본적으로 사용 중지된 앱의 변경사항이라는 섹션도 나와 있습니다. 이 섹션에 속하는 변경사항은 다양한 목적으로 제공될 수 있습니다. 이러한 변경사항을 사용 설정하기 전에 변경사항이 적용된 Android 버전의 호환성 프레임워크 목록에 있는 변경사항에 관한 설명을 읽어보세요.

logcat을 사용하여 사용 설정된 변경사항 확인

각 동작 변경사항에 관해 앱의 프로세스에서 처음으로 앱이 영향을 받는 API를 호출하면 시스템에서 다음과 같은 logcat 메시지가 출력됩니다.

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

각 logcat 메시지에는 다음 정보가 포함됩니다.

변경 ID

앱에 영향을 주는 변경사항을 나타냅니다. 이 값은 앱 호환성 변경사항 화면(그림 1 참고)에 나열된 동작 변경사항 중 하나에 매핑됩니다. 이 예에서 194833441는 NOTIFICATION_PERM_CHANGE_ID에 매핑됩니다.

UID

변경사항의 영향을 받는 앱을 나타냅니다.

상태

변경사항이 앱에 영향을 주는지 여부를 나타냅니다.

상태는 다음 값 중 하나일 수 있습니다.

상태 의미

ENABLED 변경사항이 사용 설정되어 있으며 앱에서 변경된 API를 사용하는 경우 앱의 동작에 영향을 줍니다.

상태	의미
`ENABLED`	변경사항이 사용 설정되어 있으며 앱에서 변경된 API를 사용하는 경우 앱의 동작에 영향을 줍니다.
`DISABLED`	변경사항이 사용 중지되어 있으며 앱에 영향을 주지 않습니다. 참고: 앱의 `targetSDKVersion`이 필수 기준점보다 낮아서 변경사항이 사용 중지된 경우 이 변경사항은 앱에서 상위 버전을 타겟팅하도록 `targetSDKVersion`을 높이면 기본으로 사용 설정됩니다.
`LOGGED`	변경사항이 호환성 프레임워크를 통해 기록되고 있지만 사용 설정 또는 중지할 수 없습니다. 이 변경사항은 사용 설정 여부를 바꿀 수 없지만 여전히 앱 동작에 영향을 줄 수 있습니다. 자세한 내용은 변경사항이 적용된 Android 버전의 호환성 프레임워크 목록에서 변경사항 설명을 참고하세요. 여러 경우에서 이러한 유형의 변경사항은 실험용이며 무시해도 됩니다.

DISABLED

변경사항이 사용 중지되어 있으며 앱에 영향을 주지 않습니다.

참고: 앱의 targetSDKVersion이 필수 기준점보다 낮아서 변경사항이 사용 중지된 경우 이 변경사항은 앱에서 상위 버전을 타겟팅하도록 targetSDKVersion을 높이면 기본으로 사용 설정됩니다.

LOGGED 변경사항이 호환성 프레임워크를 통해 기록되고 있지만 사용 설정 또는 중지할 수 없습니다. 이 변경사항은 사용 설정 여부를 바꿀 수 없지만 여전히 앱 동작에 영향을 줄 수 있습니다. 자세한 내용은 변경사항이 적용된 Android 버전의 호환성 프레임워크 목록에서 변경사항 설명을 참고하세요. 여러 경우에서 이러한 유형의 변경사항은 실험용이며 무시해도 됩니다.

ADB를 사용하여 사용 설정된 변경사항 확인

다음 ADB 명령어를 실행하여 전체 기기의 (사용 설정 및 사용 중지된) 전체 변경사항 세트를 확인합니다.

adb shell dumpsys platform_compat

출력에 각 변경사항에 관한 다음 정보가 나열됩니다.

변경 ID

이 동작 변경사항의 고유 식별자입니다. 예: 194833441

이름

이 동작 변경사항의 이름입니다. 예: NOTIFICATION_PERM_CHANGE_ID

targetSDKVersion 기준

변경사항을 관리하는 targetSDKVersion입니다(있는 경우).

예를 들어 이 변경사항이 SDK 버전 33 이상을 타겟팅하는 앱에 관해서만 사용 설정된 경우 enableAfterTargetSdk=32가 출력됩니다. 변경사항이 targetSDKVersion에 의해 관리되지 않으면 enableAfterTargetSdk=0이 출력됩니다.

패키지 재정의

변경사항의 기본 상태(사용 설정 또는 사용 중지)가 재정의된 각 패키지의 이름입니다.

예를 들어 기본적으로 사용 설정된 변경사항인 경우 개발자 옵션이나 ADB 중 하나를 사용하여 변경사항을 사용 중지했다면 앱의 패키지 이름이 나열됩니다. 이런 경우 출력은 다음과 같습니다.

packageOverrides={com.my.package=false}

targetSDKVersion으로 관리되는 변경사항은 기본적으로 사용 설정되거나 사용 중지될 수 있으므로, 패키지 목록에는 앱의 targetSDKVersion에 따라 true 또는 false 인스턴스가 모두 포함될 수 있습니다. 예를 들면 다음과 같습니다.

packageOverrides={com.my.package=true, com.another.package=false}

구체적인 변경사항 자세히 알아보기

호환성 프레임워크의 동작 변경사항에 관한 전체 목록은 각 Android 버전 문서에 포함됩니다. 앱을 테스트하고 있는 Android 버전과 관련된 자세한 내용은 다음 링크를 참고하세요.

변경사항을 사용 설정 또는 중지할 시점

호환성 프레임워크의 주요 목적은 Android의 최신 버전으로 앱을 테스트할 때 유연성과 제어 기능을 제공하는 것입니다. 이 섹션에서는 앱을 테스트하고 디버그할 때 변경사항의 사용 설정 또는 중지 여부를 결정하는 데 사용할 수 있는 몇 가지 전략을 설명합니다.

변경사항을 사용 중지할 시점

변경사항을 사용 중지할 시점을 결정하는 것은 일반적으로 변경사항이 targetSDKVersion으로 관리되는지 여부에 따라 다릅니다.

모든 앱에 사용 설정된 변경사항

모든 앱에 영향을 주는 변경사항은 기본적으로 앱의 targetSDKVersion과 관계없이 특정 플랫폼 버전에 사용 설정되므로 변경사항이 적용된 플랫폼 버전에서 앱을 실행해 보면 앱이 영향을 받는지 알 수 있습니다.

예를 들어, Android 15 (API 수준 35)를 타겟팅하려고 준비하고 있다면 먼저 Android 15를 실행하는 기기에 앱을 설치한 후 일반적인 테스트 워크플로를 사용하여 앱을 테스트할 수 있습니다. 앱에 문제가 발생하면 문제를 일으키는 변경사항을 사용 중지하여 다른 문제를 계속 테스트할 수 있습니다.

이러한 변경사항은 targetSDKVersion과 관계없이 모든 앱에 영향을 미칠 수 있으므로 일반적으로 targetSDKVersion으로 관리되는 변경사항을 적용하기 전에 앱을 테스트하고 업데이트해야 합니다. 이렇게 하면 사용자가 새 플랫폼 버전으로 기기를 업데이트할 때 앱 환경이 저하되는 것을 방지할 수 있습니다.

Android의 공개 출시 빌드를 사용하는 경우 이러한 변경사항을 사용 중지할 수 없으므로 이러한 변경사항에 관한 테스트를 먼저 해야 합니다. Android 버전이 미리보기 상태일 때 각 버전에서 이러한 변경사항 테스트를 실행하는 것이 이상적입니다.

targetSDKVersion으로 관리하는 변경사항

앱이 특정 targetSDKVersion을 타겟팅하는 경우 해당 버전으로 관리되는 모든 변경사항이 기본적으로 사용 설정됩니다. 따라서 앱의 targetSDKVersion을 새 버전으로 전환하면 앱은 한 번에 여러 새로운 변경사항의 영향을 받기 시작합니다.

앱이 이러한 변경사항 중 둘 이상의 변경사항에서 영향을 받을 수 있으므로 앱을 테스트하고 디버그할 때 이러한 변경사항 중 일부를 개별적으로 사용 중지해야 할 수 있습니다.

변경사항을 사용 설정할 시점

특정 targetSDKVersion으로 관리되는 변경사항은 관리되는 버전보다 낮은 SDK 버전을 타겟팅하는 앱의 경우 기본적으로 사용 중지됩니다. 일반적으로 새로운 targetSdkVersion을 타겟팅하도록 준비할 때 앱을 테스트하고 디버그해야 하는 동작 변경사항 목록이 있습니다.

예를 들어 다음 targetSdkVersion에서 일련의 플랫폼 변경사항에 관해 앱을 테스트할 수 있습니다. 앱 매니페스트를 변경하고 모든 변경사항을 한꺼번에 선택하는 대신, 개발자 옵션이나 ADB 명령어를 사용하여 각각 관리되는 변경사항을 하나씩 사용 설정하여 테스트할 수 있습니다. 이러한 추가 제어 기능 덕분에 변경사항을 개별적으로 테스트할 수 있고 앱의 여러 부분을 한 번에 디버깅하고 업데이트하는 것을 피할 수 있습니다.

변경사항을 사용 설정한 후에는 일반적인 테스트 워크플로를 사용하여 앱을 테스트하고 디버그할 수 있습니다. 문제가 발생하면 로그를 확인하여 문제의 원인을 파악합니다. 사용 설정된 플랫폼 변경사항으로 인해 문제가 발생했는지 확실하지 않으면 사용 설정된 변경사항을 사용 중지한 다음 앱의 관련 영역을 다시 테스트합니다.

변경사항 사용 설정 또는 사용 중지

호환성 프레임워크에서는 개발자 옵션이나 ADB 명령어를 사용하여 각 변경사항을 사용 설정하거나 사용 중지할 수 있습니다. 변경사항을 사용 설정하거나 사용 중지하면 앱이 비정상 종료되거나 중요한 보안 변경사항이 사용 중지될 수 있으므로 변경사항의 사용 설정 또는 중지를 바꿀 수 있는 시점에 제한사항이 몇 가지 있습니다.

개발자 옵션을 사용하여 변경사항 사용 설정 또는 중지

개발자 옵션을 사용하여 변경사항을 사용 설정하거나 사용 중지하세요. 개발자 옵션을 찾으려면 다음 단계를 따르세요.

개발자 옵션이 아직 사용 설정되지 않았다면 사용 설정합니다.
기기의 설정 앱을 열고 시스템 > 고급 > 개발자 옵션 > 앱 호환성 변경사항으로 이동합니다.
목록에서 앱을 선택합니다.
변경사항 목록에서 사용 설정하거나 사용 중지할 변경사항을 찾아 스위치를 탭합니다.

ADB를 사용하여 변경사항 사용 설정 또는 중지

ADB를 사용하여 변경사항을 사용 설정하거나 사용 중지하려면 다음 명령어 중 하나를 실행합니다.

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

CHANGE_ID(예: 194833441) 또는 CHANGE_NAME(예: NOTIFICATION_PERM_CHANGE_ID)과 앱의 PACKAGE_NAME을 전달합니다.

다음 명령어를 사용하여 단일 변경사항을 기본 상태로 재설정할 수도 있으며, 그러면 ADB 또는 개발자 옵션을 사용하여 설정한 재정의가 모두 삭제됩니다.

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

변경사항 사용 설정 또는 중지 관련 제한사항

각 동작 변경사항은 기본적으로 사용 설정되거나 사용 중지됩니다. 모든 앱에 영향을 주는 변경사항은 기본적으로 사용 설정됩니다. 다른 변경사항은 targetSdkVersion으로 관리됩니다. 이러한 변경사항은 상응하는 SDK 버전 이상을 타겟팅하는 앱의 경우 기본적으로 사용 설정되고, 관리되는 버전보다 낮은 SDK 버전을 타겟팅하는 앱의 경우 기본적으로 사용 중지됩니다. 단일 변경사항을 사용 설정하거나 사용 중지하면 기본 상태가 재정의됩니다.

호환성 프레임워크가 악의적으로 사용되는 것을 방지하기 위해 변경사항을 사용 설정 또는 중지할 수 있는 시점에 몇 가지 제한사항이 있습니다. 단일 변경사항을 사용 설정 또는 중지할 수 있는지 여부는 변경사항의 유형, 앱이 디버그 가능한지 여부, 기기에서 실행 중인 빌드의 유형에 따라 다릅니다. 다음 표에서 여러 유형의 변경사항을 사용 설정 또는 중지할 수 있는 경우를 확인하세요.

빌드 유형	디버그 불가능한 앱	디버그 가능한 앱
빌드 유형	모든 변경사항	targetSDKVersion으로 관리되는 변경사항	다른 모든 변경사항
개발자 프리뷰 또는 베타 빌드	사용 설정 또는 중지 불가능	사용 설정 또는 중지 가능	사용 설정 또는 중지 가능
공개 사용자 빌드	사용 설정 또는 중지 불가능	사용 설정 또는 중지 가능	사용 설정 또는 중지 불가능