Display a map from a mobile map package

Learn how to display a map from a mobile map package (MMPK).

display a map from a mobile map package

In this tutorial you will display a fully interactive map from a mobile map package (MMPK). The map contains a basemap layer and data layers and does not require a network connection.

Prerequisites

Before starting this tutorial:

  1. You need an ArcGIS Location Platform or ArcGIS Online account.

  2. A development and deployment environment that meets the system requirements.

  3. An IDE for Android development in Kotlin.

Steps

In this tutorial, you will first code, build, and install the app on a device, and then add the MahouRivieraTrails.mmpk.

Open an Android Studio project

  1. To start this tutorial, complete the Display a map tutorial. Or download and unzip the Display a map solution in a new folder.

  2. Modify the old project for use in this new tutorial. Expand More info for instructions.

Add import statements

  1. In the Android tool window, open app > kotlin+java > com.example.app > MainScreen.kt. Replace the import statements with the imports needed for this tutorial.

    MainScreen.kt
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    @file:OptIn(ExperimentalMaterial3Api::class)
    
    package com.example.app.screens
    
    import android.content.Context
    import android.widget.Toast
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.foundation.layout.padding
    import androidx.compose.material3.ExperimentalMaterial3Api
    import androidx.compose.material3.Scaffold
    import androidx.compose.material3.Text
    import androidx.compose.material3.TopAppBar
    import androidx.compose.runtime.Composable
    import androidx.compose.runtime.LaunchedEffect
    import androidx.compose.runtime.mutableStateOf
    import androidx.compose.runtime.remember
    import androidx.compose.ui.Modifier
    import androidx.compose.ui.platform.LocalContext
    import androidx.compose.ui.res.stringResource
    import com.arcgismaps.mapping.ArcGISMap
    import com.arcgismaps.mapping.BasemapStyle
    import com.arcgismaps.mapping.MobileMapPackage
    import com.arcgismaps.toolkit.geoviewcompose.MapView
    import com.example.app.R
    import java.io.File
    

Loading mobile map package and displaying a map

Code the app to select a map from the maps contained in a mobile map package and display the map in a map view. Use the MobileMapPackage class to access the mobile map package and load it to read its contents.

  1. In the Android tool window, open app > res > values > strings.xml. Add a string resource that specifies the file name of the mobile map package.

    strings.xml
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    <resources>
    
        <string name="app_name">Display a map from a mobile map package</string>
    
        <string name="mahourivieratrails_mmpk">MahouRivieraTrails.mmpk</string>
    
    </resources>
  2. In the Android tool window, open app > kotlin+java > com.example.app > screens > MainScreen.kt. Find the createMap() function and delete it.

    MainScreen.kt
    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    fun createMap(): ArcGISMap {
    
        return ArcGISMap(BasemapStyle.ArcGISTopographic).apply {
    
            initialViewpoint = Viewpoint(
                latitude = 34.0270,
                longitude = -118.8050,
    
                scale = 72000.0
    
            )
    
        }
    
    }
  3. Get the local Context and assign it to a variable named context. Then specify the file path where the mobile map package will be stored, and assign it to a variable named mmpkFilePath, which is a string.

    MainScreen.kt
    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    @Composable
    fun MainScreen() {
    
        val context = LocalContext.current
        // Get the path of the mobile map package
        val mmpkFilePath = context.getExternalFilesDir(null)?.path + File.separator + stringResource(id = R.string.mahourivieratrails_mmpk)
        // Create the ArcGIS Map which would use the map provided by the map package
    
        val map = remember {
    
            mutableStateOf(ArcGISMap(BasemapStyle.ArcGISTopographic))
    
        }
    
        Scaffold(
            topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
        ) {
            // Display map when the mobile map package is loaded
            MapView(
                modifier = Modifier.fillMaxSize().padding(it),
    
                arcGISMap = map.value
    
            )
        }
    }
    
    Expand
  4. Inside the remember block, replace the createMap() call with a mutable state holding a nullable ArcGISMap object. Then, in MapView, assign the map state value to the arcGISMap property.

    MainScreen.kt
    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    @Composable
    fun MainScreen() {
    
        val context = LocalContext.current
        // Get the path of the mobile map package
        val mmpkFilePath = context.getExternalFilesDir(null)?.path + File.separator + stringResource(id = R.string.mahourivieratrails_mmpk)
        // Create the ArcGIS Map which would use the map provided by the map package
    
        val map = remember {
    
            mutableStateOf(ArcGISMap(BasemapStyle.ArcGISTopographic))
    
        }
    
        Scaffold(
            topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
        ) {
            // Display map when the mobile map package is loaded
            MapView(
                modifier = Modifier.fillMaxSize().padding(it),
    
                arcGISMap = map.value
    
            )
        }
    }
    
    Expand
  5. Call the LaunchedEffect composable. In the LaunchedEffect block, load the mobile map package.

    If the mobile map package loaded successfully, get the first map stored in the mobile map package and assign it to the map state value. If the mobile map package failed to load, create a top-level showError() function and call it.

    MainScreen.kt
    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    @Composable
    fun MainScreen() {
    
        val context = LocalContext.current
        // Get the path of the mobile map package
        val mmpkFilePath = context.getExternalFilesDir(null)?.path + File.separator + stringResource(id = R.string.mahourivieratrails_mmpk)
        // Create the ArcGIS Map which would use the map provided by the map package
    
        val map = remember {
    
            mutableStateOf(ArcGISMap(BasemapStyle.ArcGISTopographic))
    
        }
    
        LaunchedEffect(Unit) {
    
            // Load the mobile map package
            val mapPackage = MobileMapPackage(mmpkFilePath)
    
            mapPackage.load().onSuccess {
                map.value = mapPackage.maps.first()
            }.onFailure { error ->
                showError(context, "Failed to load mobile map package: ${error.message}")
            }
    
        }
    
        Scaffold(
            topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
        ) {
            // Display map when the mobile map package is loaded
            MapView(
                modifier = Modifier.fillMaxSize().padding(it),
    
                arcGISMap = map.value
    
            )
        }
    }
    
    fun showError(context: Context, message: String) {
        Toast.makeText(context, message, Toast.LENGTH_LONG).show()
    }

Build and install your app

This is a necessary step, because the app install process creates the path (sdcard > Android > data > com.example.app > files) where you will upload your mobile map package to the device. Do not try to create the path manually in Device Explorer, as you will get a Operation not permitted error.

  1. Click Run > Run > app to run the app.

    Your app will be built and installed on the Android Virtual Device (AVD) that is currently selected in the Android Studio toolbar. On the AVD, you should see an ArcGISTopographic map with initial extent of the whole world. You should also see the app name Display a map from a mobile map package at the top of the screen, and the message Failed to load mobile map package: File not found. briefly displayed at the bottom. This is expected.

    Next you will add the mobile map package.

Add a mobile map package using Device Explorer

Add a mobile map package (.mmpk) to the device file system for use by your app.

  1. On your development computer, create or download the MahouRivieraTrails.mmpk mobile map package. Either complete the Create a mobile map package tutorial to create the package yourself, or download the MahouRivieraTrails.mmpk mobile map package from ArcGIS Online.

  2. In Android Studio, verify that your Android Virtual Device (AVD) is still connected. If it is not, expand More info below.

  3. Display the Device Explorer tool window, which shows the file system on your AVD. Click View > Tool Windows > Device Explorer and wait until Device Manager connects to your AVD and shows the file system tree.

  4. Upload the MahouRivieraTrails.mmpk file from your development computer.

    1. In Device Explorer, right-click on the sdcard > Android > data directory and click Synchronize.

    2. Right-click on sdcard > Android > data > com.example.app > files and click Upload. Navigate to the MahouRivieraTrails.mmpk file on your development computer. Then click OK.

      You should see a Device Explorer Toast in the lower corner confirming success.

Restart the app on your AVD

  1. Shut down the app running on your AVD. Clicking Run > Stop 'app' in Android Studio is the quickest way to stop the app.

  2. Run the app a second time by clicking Run > Run > app.

    You will see a map of trailheads, trails, and parks for the area south of the Santa Monica mountains. You can pinch (to zoom and rotate), drag, and double-tap the map view to explore the map.

What's next?

Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.