Developer

Initializing and configuring TomTom Maps and Navigation SDK

VERSION 2.1.2

TomTomSdk serves as the single entry point to the 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 exactly once per application process. 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 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    apiKey = BuildConfig.TOMTOM_API_KEY,
4)
5

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

Creating SdkConfiguration

SdkConfiguration defines the parameters you need to initialize the Navigation SDK. Example:

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

Telemetry user consent

Telemetry consent is required to collect anonymous usage data that helps improve the SDK’s performance, stability, and features. It ensures compliance with privacy regulations and transparency for users. The consent can be set to one of three values: On, Off, or Location Only.

  • 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 provideTelemetryConsent(): 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 Navigation SDK

There are several ways to safely initialize the 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            apiKey = BuildConfig.TOMTOM_API_KEY,
6            coreConfiguration = {
7                telemetryUserConsent = suspend { provideTelemetryConsent() }
8            },
9        )
10        TomTomSdk.initialize(
11            context = application,
12            sdkConfiguration = onlineOnly,
13        )
14    }
15}

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