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

호환성 프레임워크 도구

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

호환성 프레임워크 도구를 사용하면 Android 플랫폼에서 내부 로직을 자동으로 조정하므로 targetSDKVersion하거나 앱을 다시 컴파일하여 기본 테스트를 실행합니다. 왜냐하면 개별적으로 전환할 수 있으며 각 변경사항을 격리, 테스트, 디버그할 수 있습니다. 문제를 일으키는 단일 변경사항을 사용 중지하세요. 먼저 다른 것을 테스트해야 합니다

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

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

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

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

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

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

참고: 전환하려면 앱의 디버그 가능한 빌드 변형을 사용해야 합니다. 변경할 수 있습니다.

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

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

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

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

참고: Android 15 미리보기 중에 API 수준이 완료될 때까지 Android 15를 타겟팅할 때만 사용 설정되는 변경사항은 10000 35

그림 1에 기본적으로 사용 중지된 앱의 변경사항이라는 섹션도 나와 있습니다. 이 섹션에 속하는 변경사항은 다양한 목적으로 제공될 수 있습니다. 전 자세한 내용은 호환성 프레임워크 목록을 참고하세요.

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로 관리되는 변경사항은 사용 설정하거나 기본적으로 사용 중지되므로 패키지 목록에는 true 또는 false: 이러한 앱의 각 targetSDKVersion에 따라 다릅니다. 예를 들면 다음과 같습니다.

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

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

호환성 프레임워크의 동작 변경사항 전체 목록은 각 Android 버전에 대한 문서의 일부입니다. 다음 링크를 참고하세요. 더 자세한 정보를 얻을 수 있습니다. 대상:

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

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

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

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

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

모든 앱에 영향을 미치는 변경사항은 다음을 통해 사용 설정됨 특정 플랫폼 버전에 대한 기본 설정이며 targetSDKVersion 실행함으로써 앱이 영향을 받는지 확인할 수 있습니다. 해당 플랫폼 버전에서 앱을 실행합니다.

예를 들어 Android 15 (API 수준 35)를 타겟팅하려고 준비하는 경우 Android용 Chrome OS를 실행하는 기기에 앱을 설치하여 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으로 관리되는 변경사항	다른 모든 변경사항
개발자 프리뷰 또는 베타 빌드	사용 설정 또는 중지 불가능	사용 설정 또는 중지 가능	사용 설정 또는 중지 가능
공개 사용자 빌드	사용 설정 또는 중지 불가능	사용 설정 또는 중지 가능	사용 설정 또는 중지 불가능