# 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.

```kotlin
class OfflineDownloadActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_offline_download)

        RegionalOffline.beginDownloadPage(this, savedInstanceState)

        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                launch {
                    RegionalOffline.previewBundleImportStatus.collect(
                        ::renderPreviewBundleStatus,
                    )
                }
                launch {
                    RegionalOffline.downloadProgress.collect(::renderDownloadProgress)
                }
            }
        }
    }
}
```

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:

```kotlin
private fun renderPreviewBundleStatus(status: PreviewBundleImportStatus) {
    when {
        status.previewBundleReady -> showPreviewReady()
        status.waitingForNetwork -> showWaitingForNetwork()
        status.ensuring -> showPreparingResources()
        status.lastErrorCode != null -> showPreviewPreparationError(status.recoverable)
    }
}
```

_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.