Project Setup

VERSION 2.1.2

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 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.
OpenGL ES: 3.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 Narwhal Feature Drop | 2025.1.2 or higher.
JDK version 17.
Android Gradle plugin version 8.12.2.
Gradle version 8.14.3.

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.

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 us 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.
```
1android {
2    defaultConfig {
3        minSdk = 26
4        ndk {
5            abiFilters += listOf("arm64-v8a", "x86_64")
6        }
7
8        missingDimensionStrategy("tomtom-sdk-version", "complete")
9    }
10}
```
To prevent potential errors during app start-up, it’s important to ensure that OpenGL ES 3.0 support is enabled in the Android Studio emulator. If your emulator supports it, navigate to Settings, choose "Renderer maximum (up to OpenGL ES 3.1)" for the "OpenGL ES API level (requires restart)" field, and then restart the emulator to apply the changes.

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.
```
1val repositoriesTomtomComUsername: String by extra
2val repositoriesTomtomComPassword: String by extra
3
4dependencyResolutionManagement {
5    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
6    repositories {
7        google()
8        mavenCentral()
9        maven {
10            // Artifactory credentials is only needed if you use the extended flavor of the SDK
11            credentials {
12                username = repositoriesTomtomComUsername
13                password = repositoriesTomtomComPassword
14            }
15            url = uri("https://repositories.tomtom.com/artifactory/maven")
16        }
17    }
18}
```
Verify that the maven repository is correctly integrated by adding a Navigation SDK dependency to the build.gradle.kts file of your application module. For example, com.tomtom.sdk:init. Synchronize the project.
```
val version = "2.1.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.
```
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.
```
1val tomtomApiKey: String by project
2android {
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.
```
val apiKey = BuildConfig.TOMTOM_API_KEY
```

Next steps

Navigation SDK initialization