Navigation 3 가이드: 백스택부터 딥링크까지

Navigation 3에서는 앱이 백스택을 리스트로 직접 들고 있어요. 키 정의, 백스택 관리, NavDisplay와 데코레이터, ViewModel에 키 넘기기, 다이얼로그와 큰 화면, 딥링크를 1.2.1 기준으로 정리했어요.

Navigation 2에서는 NavController가 백스택을 들고 있었어요. 앱은 navigate()와 popBackStack()을 불러 간접적으로만 백스택을 바꿀 수 있었어요. Navigation 3에서는 백스택이 앱이 만든 리스트예요. 리스트에 키를 넣으면 화면이 열리고 빼면 닫혀요. 이 글에서는 지출 목록 앱을 예로 들어 키 정의부터 백스택 관리, NavDisplay, ViewModel에 키 넘기기, 다이얼로그와 큰 화면, 딥링크까지 차례로 정리해요.

코드는 Navigation 3 1.2.1, lifecycle-viewmodel-navigation3 2.11.0, adaptive-navigation3 1.3.0, Kotlin 2.4.21, kotlinx.serialization 1.13.0, Dagger Hilt 2.60.1, hilt-lifecycle-viewmodel-compose 1.4.0 기준이에요. 모두 Robolectric 테스트로 실행해 확인했어요.

1. 의존성 추가

Navigation 3 런타임과 UI, ViewModel 연동, 큰 화면용 Material 3 Adaptive, 키를 저장할 때 쓰는 kotlinx.serialization을 추가해요.

kotlin
plugins {
    id("org.jetbrains.kotlin.plugin.serialization") version "2.4.21"
}

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.2.1")
    implementation("androidx.navigation3:navigation3-ui:1.2.1")
    implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:2.11.0")
    implementation("androidx.compose.material3.adaptive:adaptive-navigation3:1.3.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.13.0")
}

serialization 플러그인은 Kotlin과 함께 배포되므로 프로젝트의 Kotlin 버전과 같은 버전을 써요. 공식 시작 가이드의 버전 목록에는 alpha 버전도 있지만 이 글은 안정 버전만 썼어요.

시작 가이드는 compileSdk 36 이상이면 된다고 하지만, 이 버전 조합은 compileSdk 37이 필요해요. 36으로 빌드하면 lifecycle-viewmodel-navigation3 2.11.0 같은 의존성이 37 이상을 요구하며 AAR 메타데이터 검사에서 실패해요. lifecycle 2.11.0과 AndroidX Hilt 1.4.0은 AGP 9.2.0 이상도 요구해요.

2. 목적지 키 정의

화면마다 키 타입을 하나씩 만들어요. 인자가 없는 화면은 data object, 인자가 있는 화면은 data class로 써요.

kotlin
@Serializable
data object ExpenseListKey : NavKey

@Serializable
data class ExpenseDetailKey(val expenseId: String) : NavKey

@Serializable
data object ExpenseSettingsKey : NavKey

@Serializable
data class DeleteExpenseKey(val expenseId: String) : NavKey

공식 문서에 따르면 키는 어떤 타입이어도 돼요. NavKey와 @Serializable은 타입 안전성보다 백스택 저장을 위한 거예요. rememberNavBackStack으로 백스택을 저장하려면 모든 키가 NavKey를 구현하고 @Serializable을 붙여야 해요. NavKey는 이 키를 저장할 수 있다고 라이브러리에 알려 주는 마커 인터페이스예요. @Serializable은 1절의 플러그인이 직렬화 코드를 만들어 줘야 동작해요. 7절의 딥링크 매처도 이 코드로 URI의 인자를 키로 바꿔요.

키에는 ID처럼 작은 값만 넣어요. 키는 백스택과 함께 저장돼요. Navigation 2 문서는 Android에서 저장 상태 전체가 쓸 수 있는 공간이 제한되어 있다고 해요. 그래서 객체 대신 ID를 넘기고 다음 화면이 그 ID로 데이터를 읽어 오게 해요.

멀티 모듈 앱이라면 공식 가이드처럼 키는 기능의 api 모듈에 두고 화면과 entryProvider는 impl 모듈에 둬요. 다른 기능의 impl 모듈이 api 모듈의 키만 보고도 그 화면으로 이동할 수 있어요.

3. 백스택을 감싸는 NavigationState

백스택을 바꾸는 코드를 한곳에 모으려고 NavigationState를 만들어요.

kotlin
@Stable
class NavigationState(
    val backStack: NavBackStack<NavKey>,
) {
    fun navigate(key: NavKey) {
        backStack.add(key)
    }

    fun goBack() {
        if (backStack.size > 1) {
            backStack.removeLastOrNull()
        }
    }
}

@Composable
fun rememberNavigationState(
    initialBackStack: List<NavKey> = listOf(ExpenseListKey),
): NavigationState {
    val backStack = rememberNavBackStack(*initialBackStack.toTypedArray())
    return remember(backStack) { NavigationState(backStack) }
}

rememberNavBackStack이 만드는 NavBackStack은 내부에 SnapshotStateList를 두고 있어서 키를 넣거나 빼면 NavDisplay가 다시 그려요. 타입을 MutableList<NavKey>로 열어 두면 일반 mutableListOf()도 넘길 수 있어요. 그러면 키가 늘어나도 화면이 바뀌지 않아요. 그래서 타입을 NavBackStack<NavKey>로 좁혔어요. rememberNavBackStack은 설정이 바뀌거나 프로세스가 종료된 뒤에도 백스택을 복원해요.

goBack에서 크기를 확인하는 이유는 백스택이 비면 NavDisplay가 IllegalArgumentException("NavDisplay backstack cannot be empty")을 던지기 때문이에요. 시스템 뒤로 가기는 이 검사와 상관없어요. 첫 화면에서는 NavDisplay가 뒤로 가기를 가로채지 않아요. onBack은 불리지 않고 시스템 기본 동작으로 넘어가요. 이 검사는 화면 안의 뒤로 버튼처럼 앱 코드가 goBack을 부를 때를 위한 거예요.

Now in Android는 상태(NavigationState)와 이동 함수(Navigator)를 나누고 하단 탭마다 백스택을 따로 둬요. 이 글의 예시는 백스택이 하나뿐이라 한 클래스로 합쳤어요.

4. NavDisplay로 화면 그리기

NavDisplay는 백스택을 받아 맨 위 키에 맞는 화면을 그려요. 키마다 어떤 화면을 그릴지는 entryProvider로 정해요.

kotlin
@Composable
fun ExpenseApp() {
    val navigationState = rememberNavigationState()

    NavDisplay(
        backStack = navigationState.backStack,
        onBack = { navigationState.goBack() },
        entryDecorators = listOf(
            rememberSaveableStateHolderNavEntryDecorator(),
            rememberViewModelStoreNavEntryDecorator(),
        ),
        entryProvider = entryProvider {
            entry<ExpenseListKey> {
                ExpenseListScreen(
                    onItemClick = { id -> navigationState.navigate(ExpenseDetailKey(id)) },
                    onSettingsClick = { navigationState.navigate(ExpenseSettingsKey) },
                )
            }
            entry<ExpenseDetailKey> { key ->
                val viewModel = hiltViewModel<ExpenseDetailViewModel, ExpenseDetailViewModel.Factory>(
                    creationCallback = { factory -> factory.create(key) },
                )
                ExpenseDetailScreen(
                    viewModel = viewModel,
                    onBackClick = { navigationState.goBack() },
                )
            }
            entry<ExpenseSettingsKey>(
                metadata = metadata {
                    put(NavDisplay.TransitionKey) {
                        slideInVertically { it } togetherWith ExitTransition.KeepUntilTransitionsFinished
                    }
                    put(NavDisplay.PopTransitionKey) {
                        EnterTransition.None togetherWith slideOutVertically { it }
                    }
                    put(NavDisplay.PredictivePopTransitionKey) {
                        EnterTransition.None togetherWith slideOutVertically { it }
                    }
                },
            ) {
                ExpenseSettingsScreen(onNavigateBack = { navigationState.goBack() })
            }
        },
    )
}

데코레이터

entryDecorators를 넘기지 않으면 기본값은 rememberSaveableStateHolderNavEntryDecorator() 하나예요. 이 데코레이터가 화면마다 rememberSaveable 상태를 저장해요. 목록을 직접 넘기면 기본값을 대신하므로 이 데코레이터도 같이 넣어야 해요.

rememberViewModelStoreNavEntryDecorator()는 엔트리마다 ViewModelStoreOwner를 줘요. 그래서 엔트리 안에서 만든 ViewModel이 그 엔트리에 묶여요. 화면을 백스택에서 빼면 ViewModel도 정리돼요(onCleared). 이 데코레이터가 없으면 ViewModel은 가장 가까운 ViewModelStoreOwner인 Activity에 묶여요. 화면을 닫아도 정리되지 않고 같은 화면을 다시 열면 이전 ViewModel을 그대로 받아요. 레퍼런스에 따르면 엔트리의 ViewModel이 SavedStateHandle을 제대로 쓰려면 이 데코레이터를 저장 상태 데코레이터와 함께 써야 해요.

화면 전환 애니메이션

설정 화면만 아래에서 올라오게 하려고 엔트리의 metadata에 전환을 넣었어요. 세 키는 화면을 열 때, 닫을 때, predictive back 제스처로 닫을 때의 전환이에요. 엔트리에 넣은 전환은 NavDisplay의 transitionSpec 같은 인자로 정한 앱 전체의 전환보다 우선해요. 정확히는 Scene의 metadata를 보는데, 한 화면씩 보여 주는 Scene은 맨 위 엔트리의 것을 그대로 써요.

5. ViewModel에 키 넘기기

Navigation 2에서는 ViewModel이 SavedStateHandle에서 인자를 꺼냈어요. Navigation 3에서는 entry 람다가 키 객체를 그대로 받으니, 그 키를 ViewModel 생성자에 넘기면 돼요. Hilt를 쓴다면 assisted injection으로 넘겨요.

kotlin
plugins {
    id("com.google.devtools.ksp")
    id("com.google.dagger.hilt.android")
}

dependencies {
    implementation("com.google.dagger:hilt-android:2.60.1")
    ksp("com.google.dagger:hilt-compiler:2.60.1")
    implementation("androidx.hilt:hilt-lifecycle-viewmodel-compose:1.4.0")
}

hiltViewModel()은 hilt-lifecycle-viewmodel-compose에서 가져와요. AndroidX Hilt 1.3.0에서 이 아티팩트로 옮겨졌고, 예전의 hilt-navigation-compose와 달리 Navigation 2에 의존하지 않아요.

ViewModel은 키를 @Assisted로 받고, Hilt가 만들어 주는 팩토리로 생성해요.

kotlin
@HiltViewModel(assistedFactory = ExpenseDetailViewModel.Factory::class)
class ExpenseDetailViewModel @AssistedInject constructor(
    @Assisted private val key: ExpenseDetailKey,
    expenseRepository: ExpenseRepository,
) : ViewModel() {
    val expense: StateFlow<Expense?> = expenseRepository.expense(key.expenseId)
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)

    @AssistedFactory
    interface Factory {
        fun create(key: ExpenseDetailKey): ExpenseDetailViewModel
    }
}

4절의 entry<ExpenseDetailKey>에서 hiltViewModel의 creationCallback으로 키를 넘겼어요. ExpenseRepository는 Hilt가 주입하고 키는 화면을 그리는 시점에 넘어와요. 키가 다른 상세 화면을 여러 개 열어도 ViewModel이 섞이지 않아요. ViewModelStoreNavEntryDecorator가 엔트리마다 ViewModelStore를 따로 두기 때문이에요. nav3-recipes의 Hilt 예제도 같은 이유로 이 데코레이터를 쓰라고 적어 두었어요.

6. 다이얼로그와 큰 화면

NavDisplay는 백스택의 엔트리를 Scene으로 묶어서 그려요. 기본은 SinglePaneSceneStrategy라 맨 위 엔트리 하나만 보여요. sceneStrategies에 전략 목록을 넘기면 앞에서부터 차례로 시도해서 처음으로 Scene을 만든 전략을 써요. 어느 전략도 Scene을 만들지 못하면 한 화면씩 보여요. 1.1.0부터는 전략 하나를 받던 sceneStrategy 대신 목록을 받는 sceneStrategies를 써요.

4절의 ExpenseApp에 다이얼로그와 목록-상세 전략을 더하면 이렇게 돼요. 바뀐 부분만 남겼어요.

kotlin
@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ExpenseApp(initialBackStack: List<NavKey> = listOf(ExpenseListKey)) {
    val navigationState = rememberNavigationState(initialBackStack)
    val dialogStrategy = remember { DialogSceneStrategy<NavKey>() }
    val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

    NavDisplay(
        // ...
        sceneStrategies = listOf(dialogStrategy, listDetailStrategy),
        entryProvider = entryProvider {
            entry<ExpenseListKey>(
                metadata = ListDetailSceneStrategy.listPane(
                    detailPlaceholder = { Text("Choose an expense") },
                ),
            ) {
                // ...
            }
            entry<ExpenseDetailKey>(
                metadata = ListDetailSceneStrategy.detailPane(),
            ) { key ->
                // ...
            }
            entry<DeleteExpenseKey>(
                metadata = DialogSceneStrategy.dialog(),
            ) { key ->
                DeleteExpenseDialog(
                    expenseId = key.expenseId,
                    onDismiss = { navigationState.goBack() },
                )
            }
            // ...
        },
    )
}

DialogSceneStrategy는 navigation3-ui에 들어 있어요. 상세 화면의 삭제 버튼이 DeleteExpenseKey를 백스택에 넣으면, metadata에 DialogSceneStrategy.dialog()를 넣은 이 엔트리가 아래 화면 위에 다이얼로그로 떠요. 상세 화면은 다이얼로그 아래에 그대로 남아요. 시스템 뒤로 가기를 누르면 다이얼로그만 닫혀요. 전략 객체는 공식 예제처럼 remember로 감싸서 리컴포지션마다 새로 만들지 않게 했어요.

ListDetailSceneStrategy는 Material 3 Adaptive의 adaptive-navigation3에 있어요. 1.3.0에서도 @ExperimentalMaterial3AdaptiveApi라서 @OptIn이 필요해요. 목록 화면에 listPane(), 상세 화면에 detailPane()을 붙이면, 넓은 창에서는 목록과 상세를 나란히 보여 주고 좁은 창에서는 한 화면씩 보여 줘요. 상세 화면을 아직 열지 않았으면 넓은 창의 오른쪽에 detailPlaceholder가 보여요.

7. 딥링크

이 글을 처음 쓴 2026년 3월에는 Navigation 3에 딥링크 API가 없어서 Intent의 URI를 직접 파싱해 키로 바꿔야 했어요. 1.2.0부터는 DeepLinkRequest와 DeepLinkMatcher로 URI를 키로 바꿀 수 있어요.

매니페스트의 Activity에 https://example.com/expenses/`로 시작하는 URI를 받는 intent-filter`를 둔 뒤, URI 패턴과 키를 연결하는 매처를 만들어요.

kotlin
val expenseDetailMatcher = UriDeepLinkMatcher(
    DeepLinkUri("https://example.com/expenses/{expenseId}"),
    serializer<ExpenseDetailKey>(),
).withBackStack { matchResult ->
    listOf(ExpenseListKey, matchResult.key)
}

fun deepLinkBackStack(intent: Intent): List<NavKey> =
    expenseDetailMatcher.match(DeepLinkRequest(intent = intent))?.backStack
        ?: listOf(ExpenseListKey)

UriDeepLinkMatcher는 URI 패턴의 {expenseId} 자리를 읽어 @Serializable 키의 같은 이름 속성에 넣어요. withBackStack으로는 딥링크로 열었을 때의 백스택을 정해요. MainActivity의 onCreate에서 deepLinkBackStack(intent)로 만든 백스택을 ExpenseApp(initialBackStack)에 넘기면 돼요.

https://example.com/expenses/7`을 담은 Intent로 앱을 열면 백스택이 [ExpenseListKey, ExpenseDetailKey("7")]`로 시작해요. 상세 화면이 바로 보이고 뒤로 가기를 누르면 목록으로 가요. 맞는 패턴이 없으면 목록 화면 하나로 시작해요.

몇 가지는 따로 챙겨야 해요.

  • DeepLinkRequest(intent = intent)와 withBackStack은 확장 함수라서 deeplink 패키지의 invoke와 withBackStack을 따로 import해야 해요.
  • Android 12부터는 앱이 도메인을 인증받지 않으면 https 링크가 앱이 아니라 기본 브라우저로 열려요. 실제 도메인이라면 intent-filter에 android:autoVerify="true"를 두고 Android App Links 인증을 거쳐야 해요.
  • 이 예시는 앱을 새로 열 때만 딥링크를 처리해요. 앱이 떠 있을 때 오는 딥링크는 onNewIntent에서 받아 지금 백스택을 바꿔야 해서, singleTop 같은 launchMode와 Activity가 바꿀 수 있는 백스택이 필요해요.

마무리

저는 Navigation 3에서 화면 이동이 리스트에 키를 넣고 빼는 일이라, 어떤 화면이 열려 있는지 백스택만 보면 알 수 있어서 다루기 쉽다고 생각해요. 처음에는 rememberNavBackStack과 데코레이터 두 개로 시작하고 다이얼로그나 큰 화면이 필요해질 때 Scene 전략을 더하기를 권해요.

참고