Map data download

You download map data to your device based on the configuration in the MapTrip Manager. Retrieve the available map data packages by calling DataSet.getAllDataSets() to identify what is configured for your devices. Configure the geographic scope of the update by passing authorized regions from getLicensedCountries() into the setCountrySelection() method. Complete the process by sequentially executing the asynchronous checkForUpdate(), loadUpdate(), and installUpdate() tasks to download and apply the map data.

Prerequisites

Paths

The download mechanism needs three important system paths.
UserDataPath: This is where the license file must be. And where settings and other files are placed.
ApplicationPath: The installation will place the map data in ApplicationPath/data. ApplicationPath/data MUST be the same path as in Api.Initialize(mapDataPath, ...)
TempPath: Temporary files might be placed here.
The three paths must be set before MapSet is used and they must be writable for the SDK. You can initialize all paths (The three system paths and the Api initialization paths) by ApiHelper.initPaths()
:material-windows: You can initialize the three system paths by Api::setSystemPaths
:material-windows: You can initialize the three system paths by Api.SetSystemPaths
The paths are defined by the system and cannot be changed.

Api State

DataSet downloads must be performed before the SDK is initialized. Everything else can lead to undefined behavior. Using DataSet downloading while Api.useMapData is set to false is not tested and unsopported.

Licensing

The information about the available packages and countries in contained in the license file. In a watermark license or a device specific license. When the download module is initialized during Api.getAllDataSets() (or apiHelper.allDataSets) it will check the license. It will always try to get a recent license from the MaptripManager to be aware of any changes since the last start or since the creation of the license. If it cannot connect to the server it will try to use a file in the UserDataPath.

val allDataSets = apiHelper.allDataSets
val myDataSet = allDataSets?.firstOrNull()

if (myDataSet != null) {

    // 2. Identify authorized regions
    // Get the list of countries allowed by your specific license
    val licensedCountries = myDataSet.getLicensedCountries()

    // 3. Configure the geographic scope
    // For example: select only the first country from your licensed list
    val selection = listOf(licensedCountries[0])
    myDataSet.setCountrySelection(selection)

    // 4. Execute the update sequence
    // These tasks must be executed in order:

    // A: Check if there is new data available on the server
    myDataSet.checkForUpdate()

    // B: Download the data to the device
    myDataSet.loadUpdate()

    // C: Apply the data so the map can use it
    myDataSet.installUpdate()
}

Explanation of the Steps

getAllDataSets()

This retrieves the "Map Packages" available to your app. Currently this only returns exactly one (or zero) packages. It might be extended in the future. Most apps will simply use the first one found. If the list is empty call Api.getLastError(Description) to get some informatin about the problem. If it is a license problem call License.getError() to get more details.

getLicensedCountries()

This returns a list of country codes (like "deu" for germany) that your license is authorized to access.

setCountrySelection()

This tells the system exactly which countries you want to download. You pass a list of country objects here to limit the download size.

The Update Trio:

Check: Communicates with the server to see if your local version is outdated.

Load: The heavy lifting—this downloads the actual map files.

Install: Moves the downloaded files into the active map folder to make them visible to the user.

Info

In a production app, the checkForUpdate, loadUpdate, and installUpdate functions return "Task" objects. In practice, you would add a listener to these tasks to know when one finishes so you can start the next one. Since downloading can take up several minutes of time it is adviced to use the onProgress event to show progress to the user.