Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

動態功能模組食譜

本做法示範如何整合動態功能模組 (DFM) 與 Navigation 3。請務必先熟悉 Play Feature Delivery，再繼續進行這項做法。

運作方式

這個範例會為三個不同模組和傳送選項中的畫面定義三個鍵：

Home：主 :app 模組中的畫面，會顯示按鈕，可導覽至動態功能模組中的畫面。
InstallTimeModule.Home：:dynamicfeature:installtime 模組中的畫面，會在提供時安裝。舉例來說，這項功能可用於新手上路模組，該模組含有豐富的資產，使用者首次安裝應用程式時需要使用，但完成新手上路程序後即可刪除。
OnDemandModule.Home：:dynamicfeature:ondemand 模組中的畫面，可隨選安裝。舉例來說，如果只有一小部分使用者會使用大型檔案大小的模組，就可能需要使用這項功能。

`DynamicModule`

DynamicModule 是用於模擬動態功能模組的抽象類別。也就是說，它會儲存相應 DynamicModuleEntryBuilder 的 moduleName 和 entryBuilderClassName (下一節會說明)。

object ExampleModule : DynamicModule(
    entryBuilderClassName = "com.example.module.ExampleEntryBuilder",
    moduleName = "example"
) {
    @Serializable
    data object Screen : AppNavKey
}

`DynamicModuleEntryBuilder`

每個動態功能模組必須包含 DynamicModuleEntryBuilder 的實作項目，用於將該模組的項目新增至主要 :app 模組中的 entryProvider。

// Inside :example module

@Suppress("unused")
class ExampleEntryBuilder : DynamicModuleEntryBuilder {
    override fun EntryProviderScope<NavKey>.build() {
        appEntry<ExampleModule.Screen> {
            ExampleScreen()
        }
    }
}

@Composable
private fun ExampleScreen() {
    // ...
}

`buildDynamicEntries()`

EntryProviderScope 的擴充功能函式，可解析該模組的 DynamicModuleEntryBuilder 並呼叫其 build() 函式。

// Inside :app module

val ALL_DYNAMIC_MODULES_MAP = listOf(
   ExampleModule,
   // ...
).associateBy { it.moduleName }

NavDisplay(
    // ...
    entryProvider = entryProvider {
        // ...
        dynamicFeatureManager.installedModules
            .mapNotNull { ALL_DYNAMIC_MODULES_MAP[it] }
            .forEach { buildDynamicEntries(it) }
    }
)

`DynamicFeatureManager`

這個類別可管理動態功能模組的安裝作業。

如要導覽至動態功能模組中包含的金鑰，請使用 installModule 方法，這個方法會自動處理安裝相應模組 (如果尚未安裝)，並在模組安裝完成時執行回呼。如果已安裝模組，系統會立即叫用這個回呼。

// Inside :app module

// Initialize the manager
val dynamicFeatureManager = retainDynamicFeatureManager()

// E.g. in a Button's onClick
dynamicFeatureManager.installModule(
    moduleName = ExampleModule.moduleName,
    onModuleInstalled = {
        backStack.add(ExampleModule.Screen)
    }
)

如要監控安裝進度，請將管理員附加至 DynamicFeatureDownloadProgressDialog 可組合函式：

DynamicFeatureDownloadProgressDialog(dynamicFeatureManager)

ProGuard 規則

為確保在開啟 R8 縮減功能時，系統可以存取 entryBuilderClassName 參照的類別，請在 proguard-rules.pro 中新增這項規則：

-keep class * implements com.example.nav3recipes.dynamicfeature.DynamicModuleEntryBuilder {
   public <init>();
}

如何在本機測試

如要測試導入作業是否正常運作，只要執行應用程式，然後前往目標模組的項目即可。根據預設，Android Studio 會在執行設定中加入所有動態功能模組。

如要模擬模組下載和安裝作業，請使用 bundletool。

提示：如果您透過 Homebrew (brew install bundletool) 安裝 bundletool，可以在下列指令中將 java -jar bundletool.jar 替換為 bundletool。

建構專案 AAB。
```
./gradlew :app:bundleDebug
```

使用 bundletool 將建構的 AAB 轉換為 APKS，並啟用本機測試。

java -jar bundletool.jar build-apks --local-testing --bundle <project-path>/app/build/outputs/bundle/debug/app-debug.aab --output app-debug.apks --overwrite

使用 bundletool 安裝轉換後的 APKS。

java -jar bundletool.jar install-apks --apks app-debug.apks

透過啟動器圖示執行應用程式。

現在首次瀏覽至隨選模組項目時，應該會看到下載進度對話方塊。

實作注意事項

DynamicFeatureManager

這項食譜一次只能支援一個安裝工作階段。如果應用程式需要同時使用多個工作階段，您應調整管理工具，以便同時追蹤多個工作階段。
這個食譜不會針對網路錯誤或內部錯誤等情況自動重試。詳情請參閱「處理要求錯誤」。
如果應用程式從其他模組存取資源和資產，請注意，這個配方不會在模組安裝後自動重新安裝 SplitCompat。

探索

在 GitHub 上查看完整食譜。

/*
 * Copyright 2026 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.dynamicfeature

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.lifecycle.compose.dropUnlessResumed
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.example.nav3recipes.content.ContentGreen
import com.example.nav3recipes.ui.setEdgeToEdgeConfig
import kotlinx.serialization.Serializable

class DynamicFeatureActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        setEdgeToEdgeConfig()
        super.onCreate(savedInstanceState)
        setContent {
            val backStack = rememberNavBackStack(Home)
            val dynamicFeatureManager = retainDynamicFeatureManager()

            DynamicFeatureDownloadProgressDialog(dynamicFeatureManager)

            NavDisplay(
                backStack = backStack,
                onBack = { backStack.removeLastOrNull() },
                modifier = Modifier.fillMaxSize(),
                entryProvider = entryProvider {
                    appEntry<Home> {
                        HomeScreen(
                            onNavigateToInstallTime = {
                                dynamicFeatureManager.installModule(
                                    moduleName = InstallTimeModule.moduleName,
                                    onModuleInstalled = {
                                        backStack.add(InstallTimeModule.Home)
                                    }
                                )
                            },
                            onNavigateToOnDemand = {
                                dynamicFeatureManager.installModule(
                                    moduleName = OnDemandModule.moduleName,
                                    onModuleInstalled = {
                                        backStack.add(OnDemandModule.Home)
                                    }
                                )
                            },
                        )
                    }

                    dynamicFeatureManager.installedModules
                        .mapNotNull { ALL_DYNAMIC_MODULES_MAP[it] }
                        .forEach { buildDynamicEntries(it) }
                }
            )
        }
    }
}

@Composable
fun HomeScreen(
    onNavigateToInstallTime: () -> Unit,
    onNavigateToOnDemand: () -> Unit,
    modifier: Modifier = Modifier,
) {
    ContentGreen(
        title = "Home screen",
        modifier = modifier,
    ) {
        Column {
            Button(onClick = dropUnlessResumed { onNavigateToInstallTime() }) {
                Text(text = "Go to Install Time Module Screen")
            }
            Button(onClick = dropUnlessResumed { onNavigateToOnDemand() }) {
                Text(text = "Go to On Demand Module Screen")
            }
        }
    }
}

@Serializable
private data object Home : AppNavKey

private val ALL_DYNAMIC_MODULES_MAP = listOf(
    InstallTimeModule,
    OnDemandModule
).associateBy { it.moduleName }

object InstallTimeModule : DynamicModule(
    entryBuilderClassName = "com.example.dynamicfeature.installtime.InstallTimeEntryBuilder",
    moduleName = "installtime",
) {
    @Serializable
    data object Home : AppNavKey {
        override fun toContentKey(): Any {
            return "InstallTimeHome"
        }
    }
}

object OnDemandModule : DynamicModule(
    entryBuilderClassName = "com.example.dynamicfeature.ondemand.OnDemandEntryBuilder",
    moduleName = "ondemand"
) {
    @Serializable
    data object Home : AppNavKey {
        override fun toContentKey(): Any {
            return "OnDemandHome"
        }
    }
}DynamicFeatureActivity.kt

/*
 * Copyright 2026 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.dynamicfeature

import android.content.Context
import androidx.activity.result.ActivityResultLauncher
import androidx.activity.result.IntentSenderRequest
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.Stable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.retain.retain
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.google.android.play.core.ktx.bytesDownloaded
import com.google.android.play.core.ktx.errorCode
import com.google.android.play.core.ktx.sessionId
import com.google.android.play.core.ktx.status
import com.google.android.play.core.ktx.totalBytesToDownload
import com.google.android.play.core.splitinstall.SplitInstallManagerFactory
import com.google.android.play.core.splitinstall.SplitInstallRequest
import com.google.android.play.core.splitinstall.SplitInstallSessionState
import com.google.android.play.core.splitinstall.SplitInstallStateUpdatedListener
import com.google.android.play.core.splitinstall.model.SplitInstallSessionStatus

@Composable
fun retainDynamicFeatureManager(): DynamicFeatureManager {
    val applicationContext = LocalContext.current.applicationContext

    val manager = retain {
        DynamicFeatureManager(applicationContext)
    }

    DisposableEffect(manager) {
        onDispose {
            manager.dispose()
        }
    }

    return manager
}

sealed interface InstallStatus {
    data object Idle : InstallStatus
    data class Pending(val sessionId: Int) : InstallStatus
    data class Downloading(val sessionId: Int, val progress: Float) : InstallStatus
    data class Installing(val sessionId: Int) : InstallStatus
    data class RequiresUserConfirmation(val state: SplitInstallSessionState) : InstallStatus
    data class Failed(val sessionId: Int, val errorCode: Int) : InstallStatus
}

@Stable
class DynamicFeatureManager(context: Context) {
    private val splitInstallManager = SplitInstallManagerFactory.create(context)

    // Maintain a single listener for the lifetime of the manager
    private val listener = SplitInstallStateUpdatedListener { state ->
        val sessionId = state.sessionId
        // Capture session ID if we're expecting an install but haven't got the ID yet (race condition)
        if (activeSessionId == null && activeModuleName != null) {
            if (state.moduleNames().contains(activeModuleName)) {
                activeSessionId = sessionId
            }
        }

        if (sessionId == activeSessionId) {
            updateStatus(state)
        }
    }

    private var activeSessionId: Int? = null
    private var activeModuleName: String? = null
    private var onModuleInstalledCallback: (() -> Unit)? = null

    var status by mutableStateOf<InstallStatus>(InstallStatus.Idle)
        private set

    var installedModules: Set<String> by mutableStateOf(splitInstallManager.installedModules.toSet())
        private set

    init {
        splitInstallManager.registerListener(listener)
    }

    fun dispose() {
        splitInstallManager.unregisterListener(listener)
    }

    fun installModule(moduleName: String, onModuleInstalled: () -> Unit) {
        if (splitInstallManager.installedModules.contains(moduleName)) {
            onModuleInstalled()
            return
        }

        // Avoid starting multiple installs if one is already in progress
        if (status !is InstallStatus.Idle && status !is InstallStatus.Failed) return

        activeModuleName = moduleName
        onModuleInstalledCallback = onModuleInstalled
        // Use a placeholder ID to indicate we are waiting for a session
        status = InstallStatus.Pending(-1)

        splitInstallManager.startInstall(
            SplitInstallRequest.newBuilder().addModule(moduleName).build()
        ).addOnSuccessListener { sessionId ->
            if (activeSessionId == null) {
                activeSessionId = sessionId
            }
            // Only update status if it hasn't progressed beyond our placeholder
            if (status is InstallStatus.Pending && (status as InstallStatus.Pending).sessionId == -1) {
                status = InstallStatus.Pending(sessionId)
            }
        }.addOnFailureListener {
            status = InstallStatus.Failed(-1, -1)
            onModuleInstalledCallback = null
        }
    }

    private fun clearSessionState() {
        activeSessionId = null
        activeModuleName = null
        onModuleInstalledCallback = null
    }

    private fun updateStatus(state: SplitInstallSessionState) {
        val sessionId = state.sessionId
        when (state.status) {
            SplitInstallSessionStatus.PENDING -> {
                status = InstallStatus.Pending(sessionId)
            }

            SplitInstallSessionStatus.DOWNLOADING -> {
                val progress = if (state.totalBytesToDownload > 0) {
                    state.bytesDownloaded.toFloat() / state.totalBytesToDownload
                } else 0f
                status = InstallStatus.Downloading(sessionId, progress)
            }

            SplitInstallSessionStatus.DOWNLOADED -> {
                status = InstallStatus.Installing(sessionId)
            }

            SplitInstallSessionStatus.INSTALLING -> {
                status = InstallStatus.Installing(sessionId)
            }

            SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION -> {
                status = InstallStatus.RequiresUserConfirmation(state)
            }

            SplitInstallSessionStatus.INSTALLED -> {
                status = InstallStatus.Idle
                installedModules = splitInstallManager.installedModules.toSet()
                onModuleInstalledCallback?.invoke()
                clearSessionState()
            }

            SplitInstallSessionStatus.FAILED -> {
                status = InstallStatus.Failed(sessionId, state.errorCode)
                clearSessionState()
            }

            SplitInstallSessionStatus.CANCELING -> {
                status = InstallStatus.Pending(sessionId)
            }

            SplitInstallSessionStatus.CANCELED -> {
                status = InstallStatus.Idle
                clearSessionState()
            }

            SplitInstallSessionStatus.UNKNOWN -> {
                status = InstallStatus.Failed(sessionId, -1)
                clearSessionState()
            }
        }
    }

    fun startConfirmationDialogForResult(
        state: SplitInstallSessionState,
        launcher: ActivityResultLauncher<IntentSenderRequest>
    ) {
        splitInstallManager.startConfirmationDialogForResult(state, launcher)
    }

    fun cancelInstallModule() {
        activeSessionId?.let { id ->
            splitInstallManager.cancelInstall(id)
        }
        status = InstallStatus.Idle
        clearSessionState()
    }
}
DynamicFeatureManager.kt

/*
 * Copyright 2026 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.dynamicfeature

import androidx.navigation3.runtime.EntryProviderScope
import androidx.navigation3.runtime.NavKey

interface AppNavKey : NavKey {
    // By default, `toString()` is used to generate the `contentKey` for NavEntries.
    // Instead of overriding `toString()`, we provide a dedicated `toContentKey()` function to make
    // it possible to uniquely identify keys for nested objects with the same simple name
    // (e.g., `ModuleA.Home` vs `ModuleB.Home`), without polluting the `toString()` representation.
    fun toContentKey(): Any = this.toString()
}

/**
 * An extension on [EntryProviderScope] specifically for [AppNavKey]s that overrides the default
 * `contentKey` resolution. It explicitly resolves the key via `it.toContentKey()` instead of the default
 * string representation.
 */
inline fun <reified K : AppNavKey> EntryProviderScope<NavKey>.appEntry(
    noinline clazzContentKey: (key: @JvmSuppressWildcards K) -> Any = { it.toContentKey() },
    metadata: Map<String, Any> = emptyMap(),
    noinline content: @androidx.compose.runtime.Composable (K) -> Unit,
) {
    addEntryProvider(K::class, clazzContentKey, { metadata }, content)
}AppNavKey.kt

/*
 * Copyright 2026 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.dynamicfeature


import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.unit.dp
import kotlin.math.roundToInt

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun DynamicFeatureDownloadProgressDialog(
    dynamicFeatureManager: DynamicFeatureManager,
    modifier: Modifier = Modifier,
) {
    val status = dynamicFeatureManager.status

    if (status is InstallStatus.Idle) return

    val launcher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.StartIntentSenderForResult()
    ) {
        // The session status will be updated automatically via the
        // SplitInstallStateUpdatedListener in DynamicFeatureManager,
        // so no explicit handling is required here.
    }

    val progress = if (status is InstallStatus.Downloading) status.progress else 0f
    val progressPercentage = "${(progress * 100).roundToInt()}%"

    AlertDialog(
        onDismissRequest = {},
        modifier = modifier,
        title = {
            Text(text = getStatusTitle(status))
        },
        text = {
            Column(
                verticalArrangement = Arrangement.spacedBy(16.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier.fillMaxWidth(),
            ) {
                if (status is InstallStatus.Downloading) {
                    CircularProgressIndicator(
                        progress = { progress },
                        modifier = Modifier.semantics {
                            contentDescription = "Downloading: $progressPercentage"
                        }
                    )
                    Text(
                        text = progressPercentage,
                        style = MaterialTheme.typography.labelSmall,
                    )
                } else if (status !is InstallStatus.Failed && status !is InstallStatus.RequiresUserConfirmation) {
                    CircularProgressIndicator()
                }

                if (status is InstallStatus.Failed) {
                    Text(
                        text = "Error code: ${status.errorCode}",
                        color = MaterialTheme.colorScheme.error,
                        style = MaterialTheme.typography.bodySmall,
                    )
                }
            }
        },
        confirmButton = {
            if (status is InstallStatus.RequiresUserConfirmation) {
                Button(onClick = {
                    dynamicFeatureManager.startConfirmationDialogForResult(
                        status.state,
                        launcher
                    )
                }) {
                    Text(text = "Confirm Download")
                }
            }
        },
        dismissButton = {
            TextButton(onClick = dynamicFeatureManager::cancelInstallModule) {
                Text(text = "Cancel")
            }
        }
    )
}

private fun getStatusTitle(status: InstallStatus): String {
    return when (status) {
        is InstallStatus.Pending -> "Requesting..."
        is InstallStatus.Downloading -> "Downloading..."
        is InstallStatus.Installing -> "Installing..."
        is InstallStatus.RequiresUserConfirmation -> "Requires Confirmation"
        is InstallStatus.Failed -> "Installation Failed"
        else -> ""
    }
}
DynamicFeatureDownloadProgressDialog.kt

/*
 * Copyright 2026 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.dynamicfeature

import androidx.navigation3.runtime.EntryProviderScope
import androidx.navigation3.runtime.NavKey

/**
 * Base class for defining a dynamic feature module.
 *
 * Caches the [DynamicModuleEntryBuilder] instance to guarantee that the reflection instantiation
 * via [Class.forName] and [Class.newInstance] occurs exactly once per application process lifetime,
 * optimizing performance during recompositions when the `entryProvider` block is re-evaluated.
 */
abstract class DynamicModule(
    val entryBuilderClassName: String,
    val moduleName: String,
) {
    private var dynamicModuleEntryBuilder: DynamicModuleEntryBuilder? = null

    internal fun getDynamicModuleEntryBuilder(): DynamicModuleEntryBuilder {
        return dynamicModuleEntryBuilder ?: (Class.forName(entryBuilderClassName)
            .getConstructor()
            .newInstance() as DynamicModuleEntryBuilder).also { dynamicModuleEntryBuilder = it }
    }
}

/**
 * Interface that every dynamic feature module must implement to register its navigation entries.
 *
 * It is invoked by [buildDynamicEntries] to add the module's routes into the base [EntryProviderScope].
 *
 * **Example:**
 * ```kotlin
 * class ExampleEntryBuilder : DynamicModuleEntryBuilder {
 *     override fun EntryProviderScope<NavKey>.build() {
 *         appEntry<ExampleModule.Screen> {
 *             ExampleScreen()
 *         }
 *     }
 * }
 * ```
 */
fun interface DynamicModuleEntryBuilder {
    fun EntryProviderScope<NavKey>.build()
}

fun EntryProviderScope<NavKey>.buildDynamicEntries(
    module: DynamicModule,
) {
    with(module.getDynamicModuleEntryBuilder()) {
        build()
    }
}
DynamicModule.kt