Offline map setup

This guide expands upon the basic map configuration setup explained in Offline map quickstart. It provides additional use cases and more detailed explanations of the configurations.

In this guide you will see how to set up the geopolitical view, configure automatic map updates, and monitor offline map events. The code snippets in this guide will reuse the examples from the Offline map quickstart.

Configuring geopolitical view

Boundary disputes and unsettled land claims exist between nations. These issues can lead to government prohibition of maps and devices that deviate from the local interpretation of the situation.

The parameter geopoliticalView can be provided in NdsStoreConfiguration to specify which view on disputed areas should be used:

1val ndsStoreConfig =
2    NdsStoreConfiguration(
3        ndsStorePath = mapDir,
4        keystorePath = keystorePath,
5        accessPermit = NdsStoreAccessPermit.MapLicense("YOUR_MAP_LICENSE"),
6        geopoliticalView = "NLD", // Netherlands' view
7    )

The international geopolitical view is used if no national view is provided or if no geopolitical view is defined in the map for the given nation.

Configuring offline map updates

To keep the offline maps up-to-date, TomTom supports over the air (OTA) updates. OTA updates use an internet connection. Since this connection can be metered and thus potentially cost the end-user money, keeping offline maps fresh must be managed. Our SDK provides two options to manage the updates to the offline maps. These options can work in parallel:

• Automatic
• Manual updates

The SDK provides the tools needed to configure and adjust the trade-offs to your specific use cases.

Through the NdsStoreUpdaterConfiguration, you can configure the update parameters.

By default, the SDK uses the TomTom production update server. However, this can be configured to any update server. If the server requires an API key, this must be provided in the configuration.

1val customServerUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        updateServerUri = Uri.parse("https://YOUR_SERVER_URI"),
4        updateServerApiKey = "YOUR_TOMTOM_API_KEY",
5    )

Configuring automatic map updates

Automatic map updates leverage the user’s location and planned route to automatically control which map regions are kept up-to-date. The map regions that are more likely to be traversed by a user in a driving session are often referred to as relevant map regions. If the relevant regions are not in the offline map, they are added. If they are already present, they will be updated with the latest available data. The SDK identifies the relevant regions and checks if new data is available for them. Any automatic updates are executed in the background.

The 'AllRegions' configuration class allows you to set parameters for automatic updates across all regions. The RelevantRegions configuration class lets you configure automatic updates for relevant regions. The RegionsAlongRoute configuration class lets you configure automatic updates for regions along the route.

The relevant map regions can be selected as follows:

To enable the relevant map regions update based on the current location, simply set the relevantRegionsEnabled parameter to true. Additionally, you can customize the radius of the relevant regions and the update interval. For instance, if you want to check for map updates every hour within a 10-kilometer radius of the current location, you can do:

1val relevantRegionUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates =
4            defaultAutomaticNdsStoreUpdaterConfiguration.copy(
5                relevantRegions =
6                    RelevantRegions(
7                        radius = Distance.kilometers(10.0),
8                        updateInterval = 60.minutes,
9                    ),
10            ),
11    )

To configure the relevant map regions along the route, set regionsAlongRouteEnabled to true. Additionally, you can specify the radius around the route to your preferred value, e.g., 5 km:

1val alongRouteUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates =
4            defaultAutomaticNdsStoreUpdaterConfiguration.copy(
5                relevantRegions = RelevantRegions(radius = Distance.kilometers(5.0)),
6                regionsAlongRoute = RegionsAlongRoute(radius = Distance.kilometers(5.0)),
7            ),
8    )

The relevant map regions are updated with no restrictions on connectivity type - meaning that they will also download data on metered network connections (such as mobile data).

NOTE: Configuring a larger radius results in more map regions being considered for updates. Updating more regions consequently results in an increase in network data consumption and an increase in the disk space usage by the offline map. This configuration must be tuned based on the needs of the end users.

• In addition to the relevant map regions options, automatic map updates can also be configured to keep all map regions up-to-date.

That can be enabled as part of the configuration:

1val allRegionsUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = defaultAutomaticNdsStoreUpdaterConfiguration.copy(allRegions = AllRegions()),
4    )

In this case, all the map regions in the offline map are considered for updates in no particular order. This type of automatic map updates is currently restricted to run only on unmetered network connections (such as wireless networks).

NOTE: Because all regions that are available for the offline map will be installed and updated, this configuration will significantly impact the data consumption and the disk size of the offline map.

Updating current position and active route

To ensure that the NdsStoreUpdater can identify the relevant map regions, you need to update the current position or the active route for the NdsStoreUpdater.

• For relevant regions update around the current position, use the updatePosition API to update the current position.
• For relevant regions update along the route, use the updateActiveRoute API to update the active route.

You can get or subscribe to the current location via LocationProvider. To set up the LocationProvider, see the Location Provider Quickstart.

1locationProvider.addOnLocationUpdateListener {
2    ndsStoreUpdater.updatePosition(it.position)
3}
4locationProvider.enable()

Enabling/disabling map updates

Use the setUpdatesEnabled API to enable/disable updates. When updates are disabled during ongoing map operations, the operations are interrupted.

ndsStoreUpdater.setUpdatesEnabled(true)

Next steps

Since you have learned about offline maps and how to set them up, here are recommendations for the next steps:

• Manual Map Management
• Build an offline navigation app