Project setup

VERSION 1.20.0

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

Requirements and recommended tools

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

Android API Level: 26 (Android 8.0 "Oreo") 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 Ladybug | 2024.2.1 or higher.
JDK version 17.
Android Gradle plugin version 8.7.2.
Gradle version 8.10.2.

Project setup

Install Android Studio if you don’t already have it.
Make sure to use Gradle in your project. We are no longer supporting Maven. Contact us if your project is using Maven instead of Gradle.
Create a new project or open an existing one. Make sure that the minimum SDK API level is set to at least 26 (Android 8.0 "Oreo") by making the following changes in the android block of your app’s build.gradle.kts file.
```
1android {
2    defaultConfig {
3        minSdk = 26
4    }
5}
```
To prevent duplication of the libc++_shared.so file in your Android Gradle build, add the following packaging option to the android block of your app’s build.gradle.kts file.
```
1android {
2    packaging {
3        jniLibs.pickFirsts.add("lib/**/libc++_shared.so")
4    }
5}
```
This ensures that only one copy of libc++_shared.so is included in the build output, addressing the issue of multiple copies from different sources.
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.
```
1dependencyResolutionManagement {
2    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
3    repositories {
4        google()
5        mavenCentral()
6        maven {
7            url = uri("https://repositories.tomtom.com/artifactory/maven")
8        }
9    }
10}
```
Verify that everything works as expected by adding a Maps SDK dependency to the build.gradle.kts file of your application module. For example, com.tomtom.sdk.maps:map-display. Synchronize the project.
```
val version = "1.20.0"
implementation("com.tomtom.sdk.maps:map-display:$version")
```
Get your TomTom API key from the TomTom Developer Portal. To find out how, refer to the How to get a TomTom API key guide.
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
```
Declare the tomtomApiKey variable within the build.gradle.kts file, outside of the android block.
```
val tomtomApiKey: String by project
```
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.
```
1android {
2    buildFeatures {
3        buildConfig = true
4    }
5    buildTypes.configureEach {
6        buildConfigField("String", "TOMTOM_API_KEY", "\"$tomtomApiKey\"")
7    }
8}
```
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
```

Now that you’ve completed the project setup, here is what you can do next.

Learn more

After a successful project setup, you can visit the following pages with some useful suggestions on how to proceed: