Map data quickstart

This guide shows how to initialize the SDK so that it serves online map data when connected and falls back to an onboard NDS map when connectivity is lost.

After following its steps the SDK is initialized with both map data sources: a prefetching online cache and an onboard region store.

For the conceptual model — the two data sources and what changes when connectivity drops — read Map data overview first.

Prerequisites

• A TomTom API key that includes the map data entitlements used on these pages. Contact Sales to obtain one.
• Project setup: configure your project as described in the Project setup guide.
• An onboard map setup package.
  • Available on request — Contact Sales if you do not yet have one. The package contains the NDS region store (the directory holding ROOT.NDS), a keystore file, and the keystore’s password (if the keystore is protected). Without it the SDK can still run — it simply has no onboard fallback if connectivity is lost long enough to exhaust the cache.
  • Plan where the package lives on the device: absolute, writable paths for the region store directory and the keystore file. Ship the package contents in your application’s assets and copy them to the device on first launch, or download them during provisioning; see Configure map data storage for choosing the on-device location.

The setup package maps directly onto buildSdkConfiguration arguments: the region store directory goes into regionStorePath, the keystore file into keyStorePath, and the keystore password into keyStorePassword. Map-update downloads authenticate with the same apiKey you pass to buildSdkConfiguration, so that key must carry the map-update entitlement.

Adding dependencies

Add the following module dependencies to the build.gradle.kts file of your application module and synchronize the project.

1
implementation("com.tomtom.sdk:init:2.5.3")
2
implementation("com.tomtom.sdk.datamanagement:data-store:2.5.3")

The init module provides the TomTomSdk entry point and the buildSdkConfiguration factory.

Enabling the onboard fallback

An onboard fallback is enabled by passing a regionStorePath to buildSdkConfiguration. The path points to the directory that holds the onboard NDS region store (it contains the ROOT.NDS file) from your setup package — the SDK reads the map data there, it does not create it. There is no default location: the buildSdkConfiguration variants without a regionStorePath parameter configure the SDK without any onboard region store.

You never construct the runtime components yourself; the SDK creates and manages the online cache and the onboard region store from this configuration.

1. Build the SdkConfiguration. The regionStorePath must point at the NDS region store directory shipped in your setup package, and keyStorePath at its keystore file:

   1
   val sdkConfig = buildSdkConfiguration(
   2
       context = context,
   3
       apiKey = apiKey,
   4
       regionStorePath = File(context.filesDir, "region-store"),
   5
       telemetryUserConsent = { UserConsent.TelemetryOn },
   6
       regionStoreConfiguration = {
   7
           keyStorePath = File(context.filesDir, "keystore")
   8
       },
   9
   )

2. Initialize the SDK:

   1
   TomTomSdk.initialize(context, sdkConfig)

From here both map data sources are up; the SDK components you obtain from TomTomSdk use them automatically. Continue with the Starting navigation guide to put the map data to use.

Running without an onboard fallback

Calling buildSdkConfiguration without a regionStorePath argument returns a configuration without an onboard region store — no default path is substituted. The SDK then relies entirely on online data and its in-memory and disk cache; it stops serving map data if connectivity is lost long enough to exhaust the cache.

1
val sdkConfig = buildSdkConfiguration(
2
    context = context,
3
    apiKey = apiKey,
4
    telemetryUserConsent = { UserConsent.TelemetryOn },
5
)

Use this configuration only when you are sure your users will always be connected and you want to skip provisioning a region store.

Verifying the integration

Build and run your application. With an onboard fallback configured you should observe the following:

1. On the first launch with connectivity, the map appears on screen and the SDK downloads the online tiles for the current area and any active route.
2. With airplane mode enabled mid-route, turn-by-turn guidance continues uninterrupted as long as the upcoming route is covered either by the online cache or by the onboard region store.
3. When the drive moves beyond the prefetched area while still offline, the SDK switches to the onboard region store and operation simply continues — uninterrupted guidance past the cached corridor is the fallback working.
4. New routes and searches require connectivity, while the active route keeps progressing offline.

If the fallback does not engage as expected, see Troubleshooting.

Next steps