Developer

Initializing and configuring the SDK

VERSION 2.4.1

This guide describes how to initialize the Maps and Navigation SDK from a single entry point and where to place the call in your Android app (Compose, ViewModel, Activity/Fragment, or with DI), and access SDK components afterward.

Initialize the Maps and Navigation SDK

TomTomSdk serves as the single entry point to the Maps and Navigation SDK. Its purpose is to simplify usage by centralizing initialization and providing consistent, straightforward access to core navigation features—such as navigation, search, reverse geocoding, and route planning—with minimal setup.

Initialization requirements

  • The SDK must be initialized only once. A second call will throw an IllegalStateException.
  • Initialization must occur on a worker thread (not on the main/UI thread) before using any SDK components.
  • Re-initialization is not required during configuration changes (e.g., device rotation), Activity recreation (onStop / onDestroy), or navigation between screens, as long as the process remains alive.
  • If the operating system kills the app process, the SDK must be initialized again during the next cold start.

Key points

  • Context: Always pass the applicationContext, not an Activity or Fragment context.
  • Telemetry consent: Ensure that telemetry consent is collected via your own UX flow before calling initialize().

Before starting with the Maps and Navigation SDK initialization make sure to configure the project as described in the Project setup guide.

The following example shows how to initialize TomTomSdk with the minimum required configuration:

1val sdkConfiguration = buildSdkConfiguration(
2    context = context, // Use application context
3    // See section: Telemetry user consent
4    telemetryUserConsent = suspend { getTelemetryConsent() },
5    apiKey = BuildConfig.TOMTOM_API_KEY,
6)
7

8TomTomSdk.initialize(
9    context = context, // Application context (recommended)
10    sdkConfiguration = sdkConfiguration, // See section: Creating SdkConfiguration for different modes
11)

Choosing and creating your SdkConfiguration

The Maps and Navigation SDK offers two ways to handle data and connectivity. Choose the configuration that best matches your target user experience, data consumption goals, and disk space budget.

Online navigation with local cache

This configuration uses TomTom’s online services as the primary data source, utilizing a local cache to bridge minor connectivity interruptions.

  • Best for: Applications where low on-device storage is a priority.
  • How it works: Uses online services primarily. Navigation continuity during short connectivity gaps is supported through local cache.
1val onlineOnly = buildSdkConfiguration(
2    context = context, // Use application context
3    apiKey = BuildConfig.TOMTOM_API_KEY,
4    // See section: Telemetry user consent
5    telemetryUserConsent = suspend { getTelemetryConsent() },
6)

Online navigation with an offline fallback (Beta)

This API is currently in Beta status. Using this API requires an explicit opt-in.

This configuration delivers a seamless experience by combining online services with pre-downloaded map data.

  • Best for: Applications requiring an uninterrupted user experience in areas with unstable or no connectivity.
  • How it works: The SDK prioritizes online services but provides full fallback support for extended offline scenarios by switching to pre-downloaded maps.

This configuration requires offline maps to be downloaded into a writable directory on the device.

Obtaining a sample offline map for development

If you require a production-ready map, Contact Sales to get started.

To test the offline fallback functionality during development, you can use TomTom’s sample map. Set it up in two steps:

1. Add the sample map dependency

Add the following to your build.gradle.kts:

implementation(libs.tomtomSdkDatamanagementNds.sampleMap)

This dependency is defined in libs.versions.toml:

tomtomSdkDatamanagementNds-sampleMap = { group = "com.tomtom.sdk.datamanagement.nds", name = "sample-map", version.ref = "tomtomNavsdk" }

The dependency automatically provides the sample map files as app assets (sample-map/map.zip and sample-map/keystore.zip).

2. Extract the sample map files and configure the SDK

Before configuring the SDK, extract the map and keystore files from your app’s assets to a writable directory on the device. See the Open Source Example app for a reference implementation.

Then pass the extracted map and keystore directories to the SDK configuration:

1val onlineFirst = buildSdkConfiguration(
2    context = context,
3    apiKey = BuildConfig.TOMTOM_API_KEY,
4    // See section: Telemetry user consent
5    regionStorePath = mapFile, // Extracted offline map files e.g., File(filesDir, "maps")
6    telemetryUserConsent = { getTelemetryConsent() },
7    regionStoreConfiguration = {
8        keyStorePath = keyStoreFile // Extracted keystore file
9        keyStorePassword = "" // Empty for sample maps, or use provided TomTom keystore password
10    },
11)

Sample map limitations:

The sample map provided is intended for demonstration and testing purposes only. It has usage limits and is not suitable for production applications.

To verify that this configuration is working as expected, you can follow the guide available in the Open Source Example app.

Telemetry user consent

Telemetry consent is required to collect pseudonymous data that helps improve the SDK’s performance, stability, and features. It ensures compliance with privacy regulations and transparency for users. To know more about Telemetry, go to Telemetry Configuration

  • The initializer takes: telemetryUserConsent: suspend () → UserConsent, which defines how the SDK retrieves the user’s telemetry consent asynchronously.
  • You must obtain consent from the user via your app’s UX (e.g., a dialog or onboarding screen) and return the result from this suspend lambda.
  • Typical flow:
    1. On first app start, show a consent dialog.
    2. Persist the choice (e.g., in DataStore/SharedPreferences).
    3. In the initializer lambda, return the stored UserConsent (or collect it on first run).

Example consent provider:

1suspend fun getTelemetryConsent(): UserConsent {
2    // Load saved choice or ask the user via your UI flow.
3    // Return the corresponding UserConsent value.
4    return loadConsentFromStorage() // Your implementation
5}

How to initialize safely the Maps and Navigation SDK

There are several ways to safely initialize the Maps and Navigation SDK: including directly in the MainActivity, using a ViewModel, or leveraging external dependency injection libraries. Regardless of the chosen approach, ensure that the initialize() method is:

  • Called only once.
  • Executed off the main thread.
  • Invoked after telemetry consent has been obtained.

Below is an example of initialization performed directly in the onCreate method of the MainActivity class:

1lifecycleScope.launch {
2    if (!TomTomSdk.isInitialized) {
3        val onlineOnly = buildSdkConfiguration(
4            context = application,
5            telemetryUserConsent = suspend { getTelemetryConsent() },
6            apiKey = BuildConfig.TOMTOM_API_KEY,
7        )
8        TomTomSdk.initialize(
9            context = application,
10            sdkConfiguration = onlineOnly,
11        )
12    }
13}

This approach should only be applied after telemetry consent has been determined. This solution is robust against configuration changes—whether the device is rotated or the app is moved to the background, the singleton instance persists, and the isInitialized flag prevents reinitialization.

Accessing SDK components after initialization

After TomTomSdk.isInitialized is true, you can access components and create clients:

1// Access the location provider for managing device location
2val locationProvider = TomTomSdk.locationProvider
3// Access the navigation object for route management
4val navigation = TomTomSdk.navigation
5// Create a Search client for location search functionality
6val search = TomTomSdk.createSearch()
7// Create a ReverseGeocoder client for address lookup
8val reverseGeocoder = TomTomSdk.createReverseGeocoder()
9// Create a RoutePlanner client for calculating routes
10val routePlanner = TomTomSdk.createRoutePlanner()

Calling these before initialization throws IllegalStateException.

Next Steps