Quickstart

VERSION 1.1.0

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:1.1.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 opting for external storage, you should be aware of the following limitations:

Permissions: Adjust your application to request the necessary permissions for accessing external storage. For detailed instructions, refer to the section on Permissions and access to external storage.
Filesystem in Userspace (FUSE): Note that Android 11 or higher defaults to using Filesystem in Userspace (FUSE) for SD cards. FUSE can significantly affect performance when dealing with large files, impacting SDK components’ performance.

It is strongly recommended to consult the Android Developer Guide on Mitigating FUSE Performance. This guide provides a comprehensive understanding and potential workarounds for performance issues related to FUSE.

Loading the offline map

The offline map must be compliant with the Navigation Data Standard version 2.4.6. Other Navigation Data Standard versions are not supported.

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:

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") // NdsStoreUpdater will create this directory
6val persistentDir = rootDir.resolve("persistent") // NdsStoreUpdater will create this directory
```
Create the NdsStoreConfiguration object:
```
1val defaultNdsStoreConfig = NdsStoreConfiguration(
2    ndsStorePath = mapDir,
3    keystorePath = keystorePath,
4    accessPermit = NdsStoreAccessPermit.MapLicense("YOUR_MAP_LICENSE")
5)
```
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)
```
Set up the NdsStoreUpdaterConfiguration:
```
1val defaultUpdateConfig = NdsStoreUpdaterConfiguration(
2    updateStoragePath = updateDir,
3    persistentStoragePath = persistentDir,
4    updateServerApiKey = TOMTOM_API_KEY
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:

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)
```

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 {
  override fun onRegionGraphChanged(
      regionGraphResult: Result<RegionGraph, MapUpdateError>,
      mapRegionStates: Map<RegionGraphNodeId, RegionGraphNodeState>
  ) {
      regionGraphResult
          .ifSuccess {
              /* Your code goes here */
              /* For example, you can save the region graph and the states */
              rootNodes = it.roots
              nodeStates.clear()
              nodeStates.putAll(mapRegionStates)
          }
          .ifFailure {
              /* Your code goes here */
              Log.e(TAG, "Can't get RegionGraph: $it")
          }
  }
21
  override fun onMapRegionStatesChanged(mapRegionStates: Map<RegionGraphNodeId, RegionGraphNodeState>) {
      /* Your code goes here */
      /* for example, update the current states*/
      nodeStates.putAll(mapRegionStates)
  }
27}

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.