Project setup
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
andtargetCompatibility
. - 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.1.
- 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’sbuild.gradle.kts
file.1android {2 defaultConfig {3 minSdk = 264 }5} -
To prevent duplication of the
libc++_shared.so
file in your Android Gradle build, add the following packaging option to theandroid
block of your app’sbuild.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.19.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. Replaceapi_key_placeholder
with the actual TomTom API key.tomtomApiKey=api_key_placeholder -
Declare the tomtomApiKey variable within the
build.gradle.kts
file, outside of theandroid
block.val tomtomApiKey: String by project -
Map the TomTom API key property to a custom field of the gradle
BuildConfig
class in theandroid
block of your app’sbuild.gradle.kts
file.1android {2 buildFeatures {3 buildConfig = true4 }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: