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

뒤로 탐색 예측 동작 지원 추가

**그림 1.** 휴대전화에 표시되는 뒤로 탐색 예측 동작의 디자인 샘플

동작 탐색 기능인 뒤로 탐색 예측을 사용하면 사용자가 뒤로 스와이프하면 이동할 위치를 미리 볼 수 있습니다.

예를 들어 뒤로 동작을 사용하면 그림 1의 샘플과 같이 앱 뒤에 홈 화면의 애니메이션 미리보기가 표시될 수 있습니다.

Android 15부터 뒤로 탐색 예측 애니메이션의 개발자 옵션을 더 이상 사용할 수 없습니다. 이제 전체적으로 또는 활동 수준에서 뒤로 탐색 예측 동작을 선택한 앱에 홈으로 돌아가기, 교차 작업, 교차 활동과 같은 시스템 애니메이션이 표시됩니다.

이 페이지의 다음 섹션에 설명된 대로 이 홈으로 돌아가기 애니메이션을 테스트할 수 있습니다.

뒤로 탐색 예측 동작을 지원하려면 하위 호환되는 OnBackPressedCallback AppCompat 1.6.0-alpha05(AndroidX) 이상 API 또는 새 OnBackInvokedCallback 플랫폼 API를 사용하여 앱을 업데이트해야 합니다. 대부분의 앱은 하위 호환되는 AndroidX API를 사용합니다.

이 업데이트는 뒤로 탐색을 제대로 가로채는 이전 경로를 제공합니다. 여기서는 KeyEvent.KEYCODE_BACK의 뒤로 가로채기와 onBackPressed 메서드(예: Activity 및 Dialog)가 있는 클래스를 새로운 시스템 Back API로 바꾸는 작업이 진행됩니다.

Codelab 및 Google I/O 동영상

이 페이지의 문서뿐만 아니라 Codelab도 활용해 보세요. Codelab에서는 AndroidX Activity API를 사용하여 뒤로 탐색 예측 동작을 처리하는 WebView의 일반적인 사용 사례 구현을 제공합니다.

AndroidX 및 플랫폼 API 구현의 추가 예시를 보여 주는 Google I/O 동영상도 시청하세요.

기본 뒤로 탐색을 사용하는 앱 업데이트

앱에서 맞춤 뒤로 동작을 구현하는 경우가 아니라면(즉, '뒤로' 작업을 시스템에 맡김) 이 기능을 지원하도록 앱을 업데이트하는 작업은 간단합니다. 이 가이드에 설명된 대로 이 기능을 선택합니다.

또한 앱에서 Fragment 또는 Navigation Component를 사용하는 경우 AndroidX Activity 1.6.0-alpha05 이상으로 업그레이드합니다.

맞춤 뒤로 탐색을 사용하는 앱 업데이트

앱에서 맞춤 뒤로 동작을 구현하는 경우 AndroidX 사용 여부와 뒤로 탐색을 처리하는 방식에 따라 이전 경로가 달라집니다.

앱에서 AndroidX 사용	앱에서 뒤로 탐색을 처리하는 방식	권장 이전 경로(이 페이지의 링크)
예	AndroidX API	기존 AndroidX 뒤로 구현 이전
예	지원되지 않는 플랫폼 API	지원되지 않는 뒤로 탐색 API가 포함된 AndroidX 앱을 AndroidX API로 이전
아니요	지원되지 않는 플랫폼 API, 이전 가능	지원되지 않는 뒤로 탐색 API를 사용하는 앱을 플랫폼 API로 이전
아니요	지원되지 않는 플랫폼 API, 이전 불가능	필수 기능이 될 때까지 선택 연기

AndroidX 뒤로 탐색 구현 이전

이 사용 사례가 가장 일반적이며 가장 권장됩니다. 이는 맞춤 뒤로 탐색 제공에 설명된 대로 OnBackPressedDispatcher를 사용하여 맞춤 동작 탐색 처리를 구현하는 신규 또는 기존 앱에 적용됩니다.

앱이 이 카테고리에 속하는 경우 다음 단계에 따라 뒤로 탐색 예측 동작 지원을 추가하세요.

이미 OnBackPressedDispatcher API를 사용하는 API(예: Fragment 및 Navigation Component)가 뒤로 탐색 예측 동작과 원활하게 호환되도록 하려면 AndroidX Activity 1.6.0- alpha05로 업그레이드하세요.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
이 페이지에 설명된 대로 뒤로 탐색 예측 동작을 선택하세요.

지원되지 않는 뒤로 탐색 API가 포함된 AndroidX 앱을 AndroidX API로 이전

앱에서 AndroidX 라이브러리를 사용하지만 지원되지 않는 뒤로 탐색 API를 구현하거나 참조하는 경우 새 동작을 지원하기 위해 AndroidX API를 사용하도록 이전해야 합니다.

지원되지 않는 API를 AndroidX API로 이전하려면 다음 단계를 따르세요.

OnBackPressedCallback 구현을 사용하여 시스템 뒤로 처리 로직을 AndroidX의 OnBackPressedDispatcher로 이전합니다. 자세한 내용은 맞춤 뒤로 탐색 제공을 참고하세요.
뒤로 동작 가로채기를 중지할 준비가 되면 OnBackPressedCallback을 중지합니다.
OnBackPressed 또는 KeyEvent.KEYCODE_BACK을 통한 뒤로 이벤트 가로채기를 중지합니다.

AndroidX Activity 1.6.0-alpha05로 업그레이드해야 합니다.

// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"

앱 이전이 완료되면 이 페이지에 설명된 대로 뒤로 탐색 예측 동작을 선택하여 홈으로 돌아가기 시스템 애니메이션을 확인합니다.

참고: OnBackPressedCallback은 android:enableOnBackInvokedCallback 값과 관계없이 항상 호출됩니다. 즉, 시스템 애니메이션을 사용 중지해도 OnBackPressedCallback을 사용하는 경우 앱의 뒤로 처리 로직에 영향을 미치지 않습니다.

지원되지 않는 뒤로 탐색 API를 사용하는 앱을 플랫폼 API로 이전

앱에서 AndroidX 라이브러리를 사용할 수 없고 대신 지원되지 않는 API를 사용하여 맞춤 뒤로 탐색을 구현하거나 참조하는 경우 OnBackInvokedCallback 플랫폼 API로 이전해야 합니다.

지원되지 않는 API를 플랫폼 API로 이전하려면 다음 단계를 따르세요.

Android 13 이상을 실행하는 기기에서는 새 OnBackInvokedCallback API를 사용하고 Android 12 이하를 실행하는 기기에서는 지원되지 않는 API를 사용합니다.
onBackInvokedDispatcher에 OnBackInvokedCallback의 맞춤 뒤로 로직을 등록합니다. 이렇게 하면 현재 활동이 완료되는 것을 방지하고 콜백은 사용자가 시스템 뒤로 탐색을 완료하면 뒤로 작업에 응답할 수 있습니다.

뒤로 동작 가로채기를 중지할 준비가 되면 OnBackInvokedCallback을 등록 취소합니다. 그러지 않으면 시스템 뒤로 탐색을 사용할 때 사용자에게 원치 않는 동작이 표시될 수 있습니다. 예를 들어 뷰 사이에 '멈춰서' 앱을 강제 종료해야 할 수 있습니다.

다음은 onBackPressed에서 로직을 이전하는 방법을 보여주는 예입니다.

Kotlin

@Override
fun onCreate() {
    if (BuildCompat.isAtLeastT()) {
        onBackInvokedDispatcher.registerOnBackInvokedCallback(
            OnBackInvokedDispatcher.PRIORITY_DEFAULT
        ) {
            /**
             * onBackPressed logic goes here. For instance:
             * Prevents closing the app to go home screen when in the
             * middle of entering data to a form
             * or from accidentally leaving a fragment with a WebView in it
             *
             * Unregistering the callback to stop intercepting the back gesture:
             * When the user transitions to the topmost screen (activity, fragment)
             * in the BackStack, unregister the callback by using
             * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
             * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
             */
        }
    }
}

자바

@Override
void onCreate() {
  if (BuildCompat.isAtLeastT()) {
    getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
        OnBackInvokedDispatcher.PRIORITY_DEFAULT,
        () -> {
          /**
           * onBackPressed logic goes here - For instance:
           * Prevents closing the app to go home screen when in the
           * middle of entering data to a form
           * or from accidentally leaving a fragment with a WebView in it
           *
           * Unregistering the callback to stop intercepting the back gesture:
           * When the user transitions to the topmost screen (activity, fragment)
           * in the BackStack, unregister the callback by using
           * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
           * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
           */
        }
    );
  }
}

Android 13 이상에서는 OnBackPressed 또는 KeyEvent.KEYCODE_BACK을 통한 뒤로 이벤트 가로채기를 중지합니다.
앱 이전이 완료되면 이 페이지에 설명된 대로 뒤로 탐색 예측 동작을 선택하여 OnBackInvokedCallback이 적용되도록 합니다.

유사한 AndroidX OnBackPressedCallback에서는 사용할 수 없는 PRIORITY_DEFAULT 또는 PRIORITY_OVERLAY로 OnBackInvokedCallback을 등록할 수 있습니다. 경우에 따라 PRIORITY_OVERLAY에 콜백을 등록하는 것이 유용합니다.

이는 onKeyPreIme()에서 이전하고 콜백이 열린 IME 대신 뒤로 동작을 수신해야 하는 경우에 적용됩니다. IME는 열릴 때 PRIORITY_DEFAULT에 콜백을 등록합니다. PRIORITY_OVERLAY에 콜백을 등록하여 OnBackInvokedDispatcher가 열린 IME 대신 콜백에 뒤로 동작을 전달하도록 합니다.

뒤로 탐색 예측 동작 선택

사례를 기반으로 앱을 업데이트하는 방법을 결정했다면 뒤로 탐색 예측 동작을 지원하도록 선택합니다.

선택하려면 AndroidManifest.xml의 <application> 태그에서 android:enableOnBackInvokedCallback 플래그를 true로 설정합니다.

<application
    ...
    android:enableOnBackInvokedCallback="true"
    ... >
...
</application>

값을 제공하지 않으면 기본값은 false이며 다음을 실행합니다.

뒤로 탐색 예측 동작 시스템 애니메이션을 사용 중지합니다.
OnBackInvokedCallback은 무시되지만 OnBackPressedCallback 호출은 계속 작동합니다.

활동 수준에서 선택

Android 14부터 android:enableOnBackInvokedCallback 플래그를 사용하여 활동 수준에서 예측 시스템 애니메이션을 선택할 수 있습니다. 이렇게 하면 대규모 다중 활동 앱을 뒤로 탐색 예측 동작으로 더 쉽게 이전할 수 있습니다. Android 15에서는 뒤로 탐색 예측이 더 이상 개발자 옵션 뒤에 있지 않습니다. 앱은 전체적으로 또는 활동 수준에서 뒤로 탐색 예측을 선택할 수 있습니다.

다음 코드는 enableOnBackInvokedCallback을 사용하여 MainActivity에서 '홈으로 돌아가기' 시스템 애니메이션을 사용 설정하는 예를 보여줍니다.

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

이전 예에서 ".SecondActivity"에 android:enableOnBackInvokedCallback=true를 설정하면 교차 활동 시스템 애니메이션이 사용 설정됩니다.

android:enableOnBackInvokedCallback 플래그를 사용할 경우 다음 고려사항에 유의하세요.

android:enableOnBackInvokedCallback=false를 설정하면 태그를 설정한 위치에 따라 활동 수준 또는 앱 수준에서 뒤로 탐색 예측 애니메이션이 사용 중지되고 OnBackInvokedCallback 플랫폼 API 호출을 무시하도록 시스템에 지시됩니다. 그러나 OnBackPressedCallback이 이전 버전과 호환되고 Android 13 이전에는 지원되지 않는 onBackPressed API가 호출되므로 OnBackPressedCallback 호출은 계속 실행됩니다.
앱 수준에서 enableOnBackInvokedCallback 플래그를 설정하면 앱의 모든 활동에 기본값이 설정됩니다. 이전 코드 예에서와 같이 활동 수준에서 플래그를 설정하여 활동별 기본값을 재정의할 수 있습니다.

콜백 권장사항

다음은 지원되는 시스템 뒤로 콜백인 BackHandler(Compose용), OnBackPressedCallback, OnBackInvokedCallback 사용에 관한 권장사항입니다.

각 콜백을 사용 설정 및 사용 중지하는 UI 상태 확인

UI 상태는 UI를 설명하는 속성입니다. 다음의 대략적인 단계를 따르는 것이 좋습니다.

각 콜백을 사용 설정 및 사용 중지하는 UI 상태를 확인합니다.
StateFlow 또는 Compose State와 같은 관찰 가능한 데이터 홀더 유형을 사용하여 상태를 정의하고 상태가 변경될 때 콜백을 사용 설정하거나 중지합니다.

앱이 이전에 뒤로 로직을 조건문과 연결하고 있었다면 이미 뒤로 이벤트가 발생한 후에 이 이벤트에 반응하고 있음을 나타낼 수 있습니다. 최신 콜백에서는 이 패턴을 피하세요. 가능하면 콜백을 조건문 밖으로 옮기고 대신 관찰 가능한 데이터 홀더 유형에 콜백을 연결하세요.

UI 로직에 시스템 뒤로 콜백 사용

UI 로직은 UI를 표시하는 방법을 결정합니다. 시스템 뒤로 콜백을 사용하여 팝업 표시 또는 애니메이션 실행과 같은 UI 로직을 실행합니다.

앱에서 시스템 뒤로 콜백을 사용 설정하면 예측 애니메이션이 실행되지 않으며 뒤로 이벤트를 처리해야 합니다. UI가 아닌 로직만 실행하기 위해 콜백을 만들면 안 됩니다.

예를 들어, 로깅만을 위해 뒤로 이벤트를 가로챈다면 활동이나 프래그먼트 수명 주기 내에 로깅합니다.

활동-활동 사례 또는 프래그먼트-활동 사례의 경우 활동 수명 주기 내에서 onDestroy 내의 isFinishing이 true이면 로깅합니다.
프래그먼트-프래그먼트의 경우 Fragment의 뷰 수명 주기 내에서 onDestroy 내 isRemoving이 true이면 로깅합니다. 또는 FragmentManager.OnBackStackChangedListener 내에서 onBackStackChangeStarted 또는 onBackStackChangeCommitted 메서드를 사용하여 로깅합니다.

Compose의 경우 Compose 대상과 연결된 ViewModel의 onCleared() 콜백 내에 로깅합니다. 이는 Compose 대상이 백 스택에서 사라지고 소멸된 시점을 알 수 있는 최상의 신호입니다.

단일 책임 콜백 만들기

디스패처에 여러 콜백을 추가할 수 있습니다. 콜백은 스택에 추가되며, 마지막으로 추가된 지원 콜백이 뒤로 동작당 하나의 콜백으로 다음 뒤로 동작을 처리합니다.

콜백에 단일 책임이 있는 경우 콜백의 사용 설정 상태를 더 쉽게 관리할 수 있습니다. 예를 들면 다음과 같습니다.

그림 2는 스택에 각각 하나의 작업을 담당하는 여러 콜백을 보유하는 방법을 보여줍니다. 콜백은 스택에서 그 위에 있는 콜백이 사용 중지된 경우에만 실행됩니다. 이 예에서 'Are you sure...' 콜백은 사용자가 양식에 데이터를 입력할 때 사용 설정되고 그렇지 않으면 사용 중지됩니다. 콜백은 사용자가 뒤로 스와이프하여 양식을 종료할 때 확인 대화상자를 엽니다.

다른 콜백에는 뒤로 탐색 예측을 지원하는 Material 구성요소, Progress API를 사용하는 AndroidX 전환 또는 다른 맞춤 콜백이 포함될 수 있습니다.

위 콜백이 사용 중지되고 이 FragmentManager의 백 스택이 비어 있지 않으면 childFragmentManager의 콜백이 실행됩니다. 이때 childFragmentManager는 Fragment 내에 연결되어 있습니다. 이 예에서는 이 내부 콜백이 사용 중지되어 있습니다.

마찬가지로 위의 콜백이 사용 중지되고 스택이 비어 있지 않으면 supportFragmentManager의 내부 콜백이 실행됩니다. 이 동작은 탐색에 FragmentManager 또는 NavigationComponent를 사용할 때 일관됩니다. NavigationComponent는 FragmentManager를 사용하므로 이 예에서 이 콜백은 사용자가 양식에 텍스트를 입력하지 않아 'Are you sure...' 콜백이 사용 중지된 경우 실행됩니다.

마지막으로 super.onBackPressed()는 시스템 수준 콜백으로, 위 콜백이 사용 중지되면 다시 실행됩니다. 홈으로 돌아가기, 교차 활동, 교차 작업과 같은 시스템 애니메이션을 트리거하려면 supportFragmentManager의 뒤로 스택이 비어 있어야 내부 콜백이 사용 중지됩니다.

뒤로 탐색 예측 동작 애니메이션 테스트

여전히 Android 13 또는 Android 14를 사용하는 경우 그림 1에 표시된 홈으로 돌아가기 애니메이션을 테스트할 수 있습니다.

이 애니메이션을 테스트하려면 다음 단계를 완료하세요.

기기에서 설정 > 시스템 > 개발자 옵션으로 이동합니다.
뒤로 탐색 예측 애니메이션을 선택합니다.
업데이트된 앱을 실행하고, 뒤로 동작을 사용하여 실제 작동하는 모습을 확인합니다.