Map Download Lifecycle

This section deals with how to prepare the Offline Maps download screen by binding it to the Android lifecycle and monitoring preview-resource readiness before users start downloading regions.

Bind the Download Page Lifecycle

Start the download-page session by calling beginDownloadPage() when the download page opens. While the page is active, the SDK checks and imports the versioned preview_resources.db for the current data source. It automatically ends the session when the LifecycleOwner is destroyed. Invoke endDownloadPage(owner) if the page closes early.

1
class OfflineDownloadActivity : AppCompatActivity() {
2
    override fun onCreate(savedInstanceState: Bundle?) {
3
        super.onCreate(savedInstanceState)
4
        setContentView(R.layout.activity_offline_download)
5

6
        RegionalOffline.beginDownloadPage(this, savedInstanceState)
7

8
        lifecycleScope.launch {
9
            repeatOnLifecycle(Lifecycle.State.STARTED) {
10
                launch {
11
                    RegionalOffline.previewBundleImportStatus.collect(
12
                        ::renderPreviewBundleStatus,
13
                    )
14
                }
15
                launch {
16
                    RegionalOffline.downloadProgress.collect(::renderDownloadProgress)
17
                }
18
            }
19
        }
20
    }
21
}

Calling beginDownloadPage() again replaces the previous page session. Only one download-management page should own this session at a time. To end it early, pass the same owner to RegionalOffline.endDownloadPage(this) so that an old page cannot end a newer page's session.

Monitor Preview Resource Status

previewBundleImportStatus is the current download page session's StateFlow<PreviewBundleImportStatus> :

Field	Meaning	UI recommendation
`previewBundleReady`	The versioned preview bundle for the current data source is installed	Enable downloads and show "Resources ready"
`ensuring`	Downloading, validating, or importing	Show preparation progress and prevent duplicate triggers
`waitingForNetwork`	Waiting for network recovery	Prompt the user to connect to a network
`recoverable`	Whether the SDK can continue retrying automatically	If `false`, log the error and check the configuration/CDN
`lastErrorCode`	Stable diagnostic error code	Use for logs and telemetry
`lastErrorMessage`	Diagnostic text	Do not display directly as unlocalized user-facing text

Example:

1
private fun renderPreviewBundleStatus(status: PreviewBundleImportStatus) {
2
    when {
3
        status.previewBundleReady -> showPreviewReady()
4
        status.waitingForNetwork -> showWaitingForNetwork()
5
        status.ensuring -> showPreparingResources()
6
        status.lastErrorCode != null -> showPreviewPreparationError(status.recoverable)
7
    }
8
}

previewBundleReady is used only to control the download page UI. The map display page should still use the standard MapView lifecycle to set the style and not wait for previewBundleReady state.