Project Setup

VERSION 2.6.2

Start your 3 months Free Self evaluation
Register now to access Maps and Navigation SDK for Android and explore its capabilities.

This guide describes how you can set up your Android project to use the TomTom Maps and Navigation SDK. After completing the guide you should have an empty Android project that works using Maps and Navigation SDK dependencies.

Requirements and recommended tools

Before proceeding with the project setup, ensure that your project meets the following requirements:

Android ABIs: arm64-v8a and x86_64.
Android API Level:
- Min SDK Version: 26 (Android 8.0 “Oreo”) or above.
- Compile SDK Version: 35 (Android 15) or above.
NDK: version 26; other major versions may not be compatible.
Java: version 8 or later for sourceCompatibility and targetCompatibility.
Kotlin: version 1.8.0 or later.
RAM: For optimal performance, the recommended minimum RAM for your target system is 2GB. If your system cannot meet this requirement, consider using our low-end configuration.
Vulkan: 1.0 support.

For an optimal developer experience, we recommend using the following tool versions as used in our sample projects and code snippets:

Android Studio Otter Feature Drop 2 | 2025.2.2 or higher.
JDK version 17.
Android Gradle plugin version 8.13.2.
Gradle version 8.14.4.

Java compatibility

The TomTom Maps and Navigation SDK is built with Kotlin, the official language recommended by Google for Android development. Kotlin is interoperable with Java, so Java-based applications should be able to interact with its APIs despite Kotlin being the primary target. Contact us if you encounter any issues when using Java in your application.

Android Emulator compatibility

Recommended emulator configuration

For testing purposes on the Android Emulator, ensure your emulator and host machine meet the following requirements:

Android: 16 (API level 36) or higher.
Hardware acceleration: the Android emulator must be configured to use hardware acceleration, and your host machine must support it. See the Android Emulator acceleration documentation for setup instructions.
Vulkan support: the Android emulator must support Vulkan 1.0.

Performance disclaimer

Hardware acceleration is a critical requirement to run smoothly on the Android Emulator. If hardware acceleration is not available and the emulator falls back to software rendering, you may experience significantly degraded performance.

Flavors

Maps and Navigation SDK is available in two flavors: complete and extended.

complete: enables common use cases for a Turn-by-Turn navigation application. It allows developers to get started building a complete Navigation solution with the SDK using the extensive guides in the API reference and the Developer Portal. Your go-to flavor when the available configurability is sufficient for your targeted user experience.
extended: additional scope of the SDK with an extended feature set and additional configurability.

The Extended flavor of Maps and Navigation SDK for Android is only available upon request. Contact Sales to get started.

Project setup

Now that you’ve ensured your environment meets the requirements, proceed setting up your Android project with the TomTom Maps and Navigation SDK.

Create a new Android Studio project with an empty activity or open an existing one, and ensure Gradle is used in your project.
Set the minimum SDK API level to at least 26 (Android 8.0 “Oreo”) and limit the ABIs to the supported set (arm64-v8a and x86_64) by making the following changes in the android block of your app’s build.gradle.kts file.

Note that it is required to configure the Maps and Navigation SDK flavor by setting the appropriate missingDimensionStrategy as below.
```
1
android {
2
    defaultConfig {
3
        minSdk = 26
4
        ndk {
5
            abiFilters += listOf("arm64-v8a", "x86_64")
6
        }
7

8
        missingDimensionStrategy("tomtom-sdk-version", "complete")
9
    }
10
}
```

Configuring project dependencies

Add a maven block to your settings.gradle.kts file to specify the URI for repositories.tomtom.com. Credentials block is only needed for the extended flavor of the SDK and you will have to use your own credentials.

1
val repositoriesTomtomComUsername: String? by extra
2
val repositoriesTomtomComPassword: String? by extra
3

4
dependencyResolutionManagement {
5
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
6
    repositories {
7
        google()
8
        mavenCentral()
9
        maven {
10
            // Artifactory credentials are only needed if you use the extended flavor of the SDK
11
            if (repositoriesTomtomComUsername?.isNotEmpty() == true) {
12
                credentials {
13
                    username = repositoriesTomtomComUsername
14
                    password = repositoriesTomtomComPassword
15
                }
16
            }
17
            url = uri("https://repositories.tomtom.com/artifactory/maven")
18
        }
19
    }
20
}

Verify that the maven repository is correctly integrated by adding a Maps and Navigation SDK dependency to the build.gradle.kts file of your application module. For example, com.tomtom.sdk:init. Synchronize the project.
```
1
val version = "2.6.2"
2
implementation("com.tomtom.sdk:init:$version")
```
Get your TomTom API key from my.tomtom.com by selecting the Maps and Navigation SDK for Android in the Product catalog.
Store the TomTom API key to a project property in your project gradle.properties file. Replace api_key_placeholder with the actual TomTom API key.
```
1
tomtomApiKey=api_key_placeholder
```
If you get errors with the API key and you want to verify that you have set it up correctly, you can clone the TomTom Example App and run it. If you can see the map, the API key has been configured properly.

In the build.gradle.kts file, map the TomTom API key property to a custom field of the gradle BuildConfig class in the android block of your app’s build.gradle.kts file.

1
val tomtomApiKey: String by project
2
android {
3
    buildFeatures {
4
        buildConfig = true
5
    }
6
    buildTypes.configureEach {
7
        buildConfigField("String", "TOMTOM_API_KEY", "\"$tomtomApiKey\"")
8
    }
9
}

To use the TomTom API key in your application code, it is sufficient to access the newly added BuildConfig field.

1
val apiKey = BuildConfig.TOMTOM_API_KEY

Next steps

Maps and Navigation SDK initialization