Quickstart

VERSION 0.48.0
PUBLIC PREVIEW

Offline functionality for the Maps SDK and Navigation SDK for Android is only available upon request. Contact us to get started.

The Navigation SDK offers a complete navigation experience, including the ability to work with offline maps. Offline maps allow users to search for destinations, plan routes, and navigate even without an internet connection.

The offline maps are divided into map regions. A map region can be any geographical area: a city such as Amsterdam, an area inside a country such as North Holland, a country such as The Netherlands, or a region such as Benelux.

You can choose to update or install any map region so that the data is available to other components of the SDK for offline use. When used offline, the Navigation SDK only uses data from the map regions that are installed on the device.

In this guide, we will walk you through the process of setting up and using offline maps in your application.

Prerequisites

Before proceeding, ensure that you do the following:

  • Gain access: Go to repositories.tomtom.com and log in with your account. Expand the user menu in the top-right corner, and select "Edit profile" → "Generate an Identity Token". Copy the generated token and use it to specify your credentials in your project gradle.properties file:

    • Replace user_name_placeholder with the login username or email you use for repositories.tomtom.com.
    • Replace identity_token_placeholder with the generated identity token.
    repositoryUsername=user_name_placeholder
    repositoryIdentityToken=identity_token_placeholder
  • Project configuration: Add a maven block to your settings.gradle file to specify the credentials and the URI for repositories.tomtom.com.

    1dependencyResolutionManagement {
    2 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    3 repositories {
    4 google()
    5 mavenCentral()
    6 maven {
    7 credentials {
    8 username = repositoryUsername
    9 password = repositoryIdentityToken
    10 }
    11 url = uri("https://repositories.tomtom.com/artifactory/maven")
    12 }
    13 }
    14}
  • Offline setup package: This package should contain a map, a keystore, a map access license token, and an API key for map updates.

  • Project setup: Configure your project according to the instructions provided in the Project setup guide.

Adding dependencies

Add the following module dependency in the build.gradle.kts of your application module and synchronize the project.

implementation("com.tomtom.sdk.datamanagement:nds-store:0.48.0")

Storing the offline map on a device

The offline setup package includes a map and a keystore. To ensure proper access, store these files on the device in a way that allows the application to access them. You can choose to embed the files as part of the application’s assets or save them in a cloud space and retrieve them during the initial launch of the application.

If you decide to place the files on external storage, make sure to adapt your application for the required permissions. For more information, refer to Permissions and access to external storage.

Loading the offline map

To utilize the offline map, you need to instantiate the NdsStore object, which allows you to load offline map data. Other SDK components can then use it for their features.

For map management functionalities, such as enabling automatic map updates, installing or removing map regions, and querying map structures, you will need NdsStoreUpdater.

Follow these steps to construct the NdsStore and NdsStoreUpdater objects:

  1. Define the necessary file paths and directories:
    1/* Assume the map and the keystore files are stored on the app-specific storage */
    2val rootDir = context.filesDir
    3val mapDir = rootDir.resolve("map")
    4val keystorePath = rootDir.resolve("keystore.sqlite")
    5val updateDir = rootDir.resolve("update") // NdsStore will create this directory
    6val persistentDir = rootDir.resolve("persistent") // NdsStore will create this directory
  2. Create the NdsStoreConfiguration object:
    1val defaultNdsStoreConfig = NdsStoreConfiguration(
    2 ndsStorePath = mapDir,
    3 keystorePath = keystorePath,
    4 accessPermit = NdsStoreAccessPermit.MapLicense("YOUR_MAP_LICENSE")
    5)
  3. Create the NdsStore object and handle any potential failures:
    1ndsStore = NdsStore.create(context = context, configuration = defaultNdsStoreConfig).fold(
    2 { it },
    3 {
    4 /* Error handling - Your code goes here */
    5 throw IllegalStateException(it.message)
    6 }
    7)
  4. Set up the NdsStoreUpdaterConfiguration:
    1val defaultUpdateConfig = NdsStoreUpdaterConfiguration(
    2 updateStoragePath = updateDir,
    3 persistentStoragePath = persistentDir,
    4 updateServerApiKey = TOMTOM_API_KEY
    5)
  5. Create the NdsStoreUpdater object and handle any potential failures:
    1ndsStoreUpdater = NdsStoreUpdater.create(
    2 context = context,
    3 ndsStore = ndsStore,
    4 configuration = defaultUpdateConfig
    5).fold(
    6 { it },
    7 {
    8 /* Error handling - Your code goes here */
    9 throw IllegalStateException(it.toString())
    10 }
    11)

To access a specific offline map, create only one instance of NdsStore and NdsStoreUpdater. Creating multiple instances for the same map can lead to unexpected behavior.

Downloading map contents around the specified location

The offline map included in the setup package contains only metadata and does not include pre-installed map regions. Therefore, it is necessary to download and install map regions before utilizing search, display, routing, or navigation functionalities.

To enable automatic map updates around the specified location, follow these steps:

  1. Create the NdsStoreUpdater object with an NdsStoreUpdaterConfiguration that is set up to enable the updates:
    1ndsStoreUpdater = NdsStoreUpdater.create(
    2 context = context,
    3 ndsStore = ndsStore,
    4 configuration = defaultUpdateConfig.copy(
    5 automaticUpdates = defaultAutomaticNdsStoreUpdaterConfiguration.copy(
    6 relevantRegions = RelevantRegions()
    7 )
    8 )
    9).fold(
    10 { it },
    11 {
    12 /* Error handling - Your code goes here */
    13 throw IllegalStateException(it.toString())
    14 }
    15)
  2. Add an RegionGraphListener to monitor the success events of map updates, and then enable map updates:
    1private var rootNodes = listOf<RegionGraphNode>()
    2private val nodeStates = mutableMapOf<RegionGraphNodeId, RegionGraphNodeState>()
    3private val regionGraphListener = object : RegionGraphListener {
    4 override fun onRegionGraphChanged(
    5 regionGraphResult: Result<RegionGraph, MapUpdateError>,
    6 mapRegionStates: Map<RegionGraphNodeId, RegionGraphNodeState>
    7 ) {
    8 regionGraphResult
    9 .ifSuccess {
    10 /* Your code goes here */
    11 /* For example, you can save the region graph and the states */
    12 rootNodes = it.roots
    13 nodeStates.clear()
    14 nodeStates.putAll(mapRegionStates)
    15 }
    16 .ifFailure {
    17 /* Your code goes here */
    18 Log.e(TAG, "Can't get RegionGraph: $it")
    19 }
    20 }
    21
    22 override fun onMapRegionStatesChanged(mapRegionStates: Map<RegionGraphNodeId, RegionGraphNodeState>) {
    23 /* Your code goes here */
    24 /* for example, update the current states*/
    25 nodeStates.putAll(mapRegionStates)
    26 }
    27}
  3. Update the position by passing the location to the NdsStore.
    val amsterdam = GeoPoint(52.377956, 4.897070)
    ndsStoreUpdater.updatePosition(amsterdam)

The NdsStoreUpdater will download the relevant map regions around the specified location in the background. Upon successful map update, you will receive a notification from RegionGraphListener. The more details about RegionGraphListener can be found in Manual Map Management

Utilizing the NdsStore

Now that the NdsStore is created and map contents are successfully downloaded, you can use it with other SDK components. For example, you can create a route planner:

val routePlanner = OfflineRoutePlanner.create(ndsStore)

With the route planner, you can plan routes by providing the desired itinerary:

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(itinerary = Itinerary(amsterdam, rotterdam))
4val result = routePlanner.planRoute(routePlanningOptions)
5if (result.isSuccess()) {
6 /* Success - Your code goes here */
7 val route = result.value().routes.first()
8} else {
9 /* Error handling - Your code goes here */
10 val error = result.failure()
11}

Next steps

You have successfully set up and utilized offline maps with the Navigation SDK. To further enhance your offline map implementation, consider exploring the following topics:

  • Offline Map Setup: Learn more about advanced configuration options and customization possibilities for offline maps.
  • Manual Map Management: Explore how to manually manage map regions, including downloading, updating, and removing specific regions.
  • Build an offline navigation app: Learn how to implement a basic offline navigation application.

By diving deeper into these areas, you can unlock the full potential of offline maps in your application.