Initializing and configuring TomTom Maps and Navigation SDK

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.

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:

1
val sdkConfiguration = buildSdkConfiguration(
2
    context = context, // Use application context
3
    apiKey = BuildConfig.TOMTOM_API_KEY,
4
)
5

6
TomTomSdk.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:

1
val 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:

1
suspend 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:

1
lifecycleScope.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
2
val locationProvider = TomTomSdk.locationProvider
3
// Access the navigation object for route management
4
val navigation = TomTomSdk.navigation
5
// Create a Search client for location search functionality
6
val search = TomTomSdk.createSearch()
7
// Create a ReverseGeocoder client for address lookup
8
val reverseGeocoder = TomTomSdk.createReverseGeocoder()
9
// Create a RoutePlanner client for calculating routes
10
val routePlanner = TomTomSdk.createRoutePlanner()

Next Steps

• Display your first map