Download preplanned map area | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Take a map offline using a preplanned map area.

Image of download preplanned map area

Use case

Generating offline maps on demand for a specific area can be time consuming for users and a processing load on the server. If areas of interest are known ahead of time, a web map author can pre-create packages for these areas. This way, the generation only needs to happen once, making the workflow more efficient for users and servers.

An archeology team could define preplanned map areas for dig sites which can be taken offline for field use. To see the difference, compare this sample to the “Generate offline map” sample.

How to use the sample

Select a map area from the Preplanned map areas list. The download progress will be shown and when a download is complete it will be displayed in the map view.

How it works

Open the online ArcGISMap from a PortalItem and display it.
Create an OfflineMapTask using the portal item.
Get the PreplannedMapAreas from the task.
To download a selected map area, create default DownloadPreplannedOfflineMapParameters from the OfflineMapTask using the selected preplanned map area.
Set the update mode of the preplanned map area.
Use the parameters and a local path to create a DownloadPreplannedOfflineMapJob from the task.
Start the DownloadPreplannedOfflineMapJob. Once it has completed, get the DownloadPreplannedOfflineMapResult.
Get the ArcGISMap from the result and display it in the MapView.

Relevant API

DownloadPreplannedOfflineMapJob
DownloadPreplannedOfflineMapParameters
DownloadPreplannedOfflineMapResult
OfflineMapTask
PreplannedMapArea

About the data

The Naperville stormwater network map is based on ArcGIS Solutions for Stormwater and provides a realistic depiction of a theoretical stormwater network.

Additional information

PreplannedUpdateMode can be used to set the way the preplanned map area receives updates in several ways:

NoUpdates - No feature updates will be performed.
DownloadScheduledUpdates - Scheduled, read-only updates will be downloaded from the online map area and applied to the local mobile geodatabases.
DownloadScheduledUpdatesAndUploadNewFeatures - Scheduled, read-only updates are downloaded from the online map area and applied to the local mobile geodatabases. Newly added features can also be uploaded to the feature service.
SyncWithFeatureServices - Changes, including local edits, will be synced directly with the underlying feature services.

For more information about offline workflows, see Offline maps, scenes, and data in the ArcGIS Developers guide.

Sample Code

MainActivity.kt

DownloadPreplannedMapAreaViewModel.kt

DownloadPreplannedMapAreaScreen.kt

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.downloadpreplannedmaparea

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.runtime.Composable
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.esri.arcgismaps.sample.downloadpreplannedmaparea.screens.DownloadPreplannedMapAreaScreen
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
import java.io.File

class MainActivity : ComponentActivity() {

    // The directory where the offline map will be saved
    private val offlineMapPath by lazy {
        application.getExternalFilesDir(null)?.path.toString() + File.separator + application.getString(
            R.string.download_preplanned_map_area_app_name
        )
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // authentication with an API key or named user is
        // required to access basemaps and other location services
        ArcGISEnvironment.apiKey = ApiKey.create(BuildConfig.ACCESS_TOKEN)

        // Delete any existing offline maps, to reset sample state
        File(offlineMapPath).deleteRecursively()

        enableEdgeToEdge()
        setContent {
            SampleAppTheme {
                DownloadPreplannedMapAreaApp()
            }
        }
    }

    @Composable
    private fun DownloadPreplannedMapAreaApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            DownloadPreplannedMapAreaScreen(
                sampleName = getString(R.string.download_preplanned_map_area_app_name)
            )
        }
    }
}

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.downloadpreplannedmaparea.components

import android.app.Application
import androidx.compose.material3.SnackbarHostState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.PortalItem
import com.arcgismaps.portal.Portal
import com.arcgismaps.tasks.offlinemaptask.DownloadPreplannedOfflineMapJob
import com.arcgismaps.tasks.offlinemaptask.DownloadPreplannedOfflineMapParameters
import com.arcgismaps.tasks.offlinemaptask.GenerateOfflineMapJob
import com.arcgismaps.tasks.offlinemaptask.OfflineMapTask
import com.arcgismaps.tasks.offlinemaptask.PreplannedMapArea
import com.arcgismaps.tasks.offlinemaptask.PreplannedUpdateMode
import com.esri.arcgismaps.sample.downloadpreplannedmaparea.R
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialogViewModel
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import java.io.File

class DownloadPreplannedMapAreaViewModel(application: Application) : AndroidViewModel(application) {

    // The directory where the offline map will be saved
    private val offlineMapPath by lazy {
        application.getExternalFilesDir(null)?.path.toString() + File.separator + application.getString(
            R.string.download_preplanned_map_area_app_name
        )
    }

    // Create a portal to ArcGIS Online
    private val portal = Portal("https://www.arcgis.com")

    // create a portal item using the portal and the item id of a map service
    private val portalItem = PortalItem(portal, "acc027394bc84c2fb04d1ed317aac674")

    private val offlineMapTask = OfflineMapTask(portalItem)

    // A list of preplanned map areas populated by the offline map task
    private var preplannedMapAreas = mutableListOf<PreplannedMapArea>()

    // Keep a hash map of downloaded maps
    private var downloadedMapAreas: HashMap<String, ArcGISMap> = hashMapOf()

    // An online map created from the portal item
    private val onlineMap = ArcGISMap(portalItem)

    // The current map shown in the map view
    var currentMap by mutableStateOf(onlineMap)

    val preplannedMapAreaInfoList = mutableStateListOf<PreplannedMapAreaInfo>()

    // Defined to send messages related to offlineMapJob
    val snackbarHostState = SnackbarHostState()

    // Create a message dialog view model for handling error messages
    val messageDialogVM = MessageDialogViewModel()

    init {
        with(viewModelScope) {
            launch(Dispatchers.IO) {
                offlineMapTask.getPreplannedMapAreas().onSuccess {
                    // Keep a list of all preplanned map areas
                    preplannedMapAreas.addAll(it)

                    // Add all of the preplanned map areas name and download status to a list
                    it.forEachIndexed { index, preplannedMapArea ->
                        preplannedMapAreaInfoList.add(
                            PreplannedMapAreaInfo(
                                index = index,
                                name = preplannedMapArea.portalItem.title,
                                progress = 0f,
                                isDownloaded = false
                            )
                        )
                    }
                }
            }

            launch(Dispatchers.Main) {
                onlineMap.load().onFailure { messageDialogVM.showMessageDialog(it) }
            }
        }
    }

    /**
     * Show the original map from the portal item.
     */
    fun showOnlineMap() {
        currentMap = onlineMap
    }

    /**
     * Download or show the already downloaded preplanned map area.
     */
    fun downloadOrShowOfflineMap(preplannedMapAreaInfo: PreplannedMapAreaInfo) {
        if (preplannedMapAreaInfo.isDownloaded) {
            showOfflineMap(preplannedMapAreaInfo)
        } else {
            downloadOfflineMap(preplannedMapAreaInfo)
        }
    }

    /**
     * Show the offline map of the given preplanned map area name.
     */
    private fun showOfflineMap(preplannedMapAreaInfo: PreplannedMapAreaInfo) {
        downloadedMapAreas[preplannedMapAreaInfo.name]?.let { selectedArcGISMap ->
            currentMap = selectedArcGISMap
        }
    }

    /**
     * Use the [OfflineMapTask] to create [DownloadPreplannedOfflineMapParameters] for the given [PreplannedMapArea].
     * Then use the task to create a [DownloadPreplannedOfflineMapJob] to download the preplanned offline map.
     */
    private fun downloadOfflineMap(preplannedMapAreaInfo: PreplannedMapAreaInfo) {
        viewModelScope.launch(Dispatchers.IO) {
            // Get the area of interest for the preplanned map area
            preplannedMapAreas.find { it.portalItem.title == preplannedMapAreaInfo.name }?.let { preplannedMapArea ->
                // Create default download parameters from the offline map task
                offlineMapTask.createDefaultDownloadPreplannedOfflineMapParameters(preplannedMapArea).onSuccess {
                    // Set the update mode to receive no updates
                    it.updateMode = PreplannedUpdateMode.NoUpdates
                    // Define the path where the map will be saved
                    val downloadDirectoryPath = offlineMapPath + File.separator + preplannedMapAreaInfo.name
                    File(downloadDirectoryPath).mkdirs()
                    // Create a job to download the preplanned offline map
                    val downloadPreplannedOfflineMapJob = offlineMapTask.createDownloadPreplannedOfflineMapJob(
                        parameters = it, downloadDirectoryPath = downloadDirectoryPath
                    )
                    runOfflineMapJob(downloadPreplannedOfflineMapJob, preplannedMapAreaInfo)
                }
            }
        }
    }

    /**
     * Starts the [GenerateOfflineMapJob], shows the progress dialog and displays the result offline map to the MapView.
     */
    private fun runOfflineMapJob(
        downloadPreplannedOfflineMapJob: DownloadPreplannedOfflineMapJob,
        preplannedMapAreaInfo: PreplannedMapAreaInfo
    ) {
        with(viewModelScope) {
            // Collect the job's progress flow
            val progressCoroutine = launch(Dispatchers.IO) {
                downloadPreplannedOfflineMapJob.progress.collect { progress ->
                    // Update the UI to this preplanned map area's downloads progress
                    preplannedMapAreaInfoList[preplannedMapAreaInfo.index] =
                        preplannedMapAreaInfo.copy(progress = progress.toFloat() / 100)
                }
            }
            // Start the job and handle the result
            launch(Dispatchers.IO) {
                // Start the job and wait for Job result
                downloadPreplannedOfflineMapJob.start()
                downloadPreplannedOfflineMapJob.result().onSuccess { downloadedMap ->
                    // Set the offline map result as the displayed
                    currentMap = downloadedMap.offlineMap
                    // Update the UI to show the map as downloaded
                    preplannedMapAreaInfoList[preplannedMapAreaInfo.index] =
                        preplannedMapAreaInfo.copy(isDownloaded = true)
                    // Add the downloaded map to the list of downloaded maps
                    downloadedMapAreas[preplannedMapAreaInfo.name] = downloadedMap.offlineMap
                    // Show user where map was locally saved
                    snackbarHostState.showSnackbar(message = "Map saved at: " + downloadPreplannedOfflineMapJob.downloadDirectoryPath)
                }.onFailure { messageDialogVM.showMessageDialog(it) }
                // Cancel the coroutine handling progress reporting
                progressCoroutine.cancel()
            }
        }
    }
}

data class PreplannedMapAreaInfo(val index: Int, val name: String, val progress: Float, val isDownloaded: Boolean)

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.downloadpreplannedmaparea.screens

import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Settings
import androidx.compose.material3.Card
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.ModalBottomSheet
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.Text
import androidx.compose.material3.rememberModalBottomSheetState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.runtime.snapshots.SnapshotStateList
import androidx.compose.ui.Alignment
import androidx.compose.ui.Alignment.Companion.CenterVertically
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.toolkit.geoviewcompose.MapView
import com.esri.arcgismaps.sample.downloadpreplannedmaparea.R
import com.esri.arcgismaps.sample.downloadpreplannedmaparea.components.DownloadPreplannedMapAreaViewModel
import com.esri.arcgismaps.sample.downloadpreplannedmaparea.components.PreplannedMapAreaInfo
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialog
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar

/**
 * Main screen layout for the sample app
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun DownloadPreplannedMapAreaScreen(sampleName: String) {
    val mapViewModel: DownloadPreplannedMapAreaViewModel = viewModel()

    // Set up the bottom sheet controls
    var showBottomSheet by remember { mutableStateOf(false) }
    val sheetState = rememberModalBottomSheetState(skipPartiallyExpanded = true)

    Scaffold(snackbarHost = { SnackbarHost(hostState = mapViewModel.snackbarHostState) },
        topBar = { SampleTopAppBar(title = sampleName) },
        content = {
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(it),
            ) {
                MapView(
                    modifier = Modifier
                        .fillMaxSize()
                        .weight(1f),
                    arcGISMap = mapViewModel.currentMap,
                )
                // Show bottom sheet with override parameter options
                if (showBottomSheet) {
                    ModalBottomSheet(
                        modifier = Modifier.wrapContentSize(),
                        sheetState = sheetState,
                        onDismissRequest = { showBottomSheet = false }
                    ) {
                        DownloadPreplannedMap(
                            mapViewModel::showOnlineMap,
                            mapViewModel::downloadOrShowOfflineMap,
                            mapViewModel.preplannedMapAreaInfoList
                        )
                    }
                }
            }
            mapViewModel.messageDialogVM.apply {
                if (dialogStatus) {
                    MessageDialog(
                        title = messageTitle, description = messageDescription, onDismissRequest = ::dismissDialog
                    )
                }
            }
        },
        floatingActionButton = {
            if (!showBottomSheet) {
                FloatingActionButton(modifier = Modifier.padding(bottom = 36.dp, end = 12.dp),
                    onClick = { showBottomSheet = true }) {
                    Icon(
                        Icons.Filled.Settings, contentDescription = "Select map"
                    )
                }
            }
        })
}

@Composable
fun DownloadPreplannedMap(
    showOnlineMap: () -> Unit,
    downloadOrShowMap: (PreplannedMapAreaInfo) -> Unit,
    preplannedMapAreaInfoList: SnapshotStateList<PreplannedMapAreaInfo>
) {
    Column(
        modifier = Modifier
            .wrapContentSize()
            .background(MaterialTheme.colorScheme.background)
            .padding(12.dp)
            .verticalScroll(rememberScrollState()),
        horizontalAlignment = Alignment.Start,
    ) {
        Text(
            modifier = Modifier
                .align(Alignment.CenterHorizontally)
                .padding(16.dp),
            text = "Select map",
            style = MaterialTheme.typography.titleLarge
        )
        Card(modifier = Modifier.wrapContentSize()) {
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(8.dp)
                    .clickable { showOnlineMap() },
                horizontalArrangement = Arrangement.spacedBy(4.dp),
                verticalAlignment = CenterVertically,
            ) {
                Text("Web map (online)")
            }
        }
        Text(text = "Preplanned map areas", modifier = Modifier.padding(top = 16.dp, start = 8.dp, bottom = 4.dp))
        Card(modifier = Modifier.wrapContentSize()) {
            preplannedMapAreaInfoList.forEach {
                Row(
                    modifier = Modifier
                        .fillMaxWidth()
                        .clickable { downloadOrShowMap(it) }
                        .padding(8.dp),
                    horizontalArrangement = Arrangement.spacedBy(4.dp),
                    verticalAlignment = CenterVertically,
                ) {
                    if (!it.isDownloaded) {
                        if (it.progress <= 0) {
                            Icon(
                                painter = painterResource(R.drawable.download_to_24),
                                contentDescription = "Download"
                            )
                        } else {
                            CircularProgressIndicator(
                                modifier = Modifier.requiredSize(18.dp),
                                progress = { it.progress })
                        }
                    }
                    Text(
                        text = it.name, color = if (it.isDownloaded) {
                            MaterialTheme.colorScheme.onSurface
                        } else {
                            MaterialTheme.colorScheme.outline
                        }
                    )
                }
                HorizontalDivider()
            }
        }
    }
}