Developer

Project setup

VERSION 1.26.2

Navigation SDK for Android is only available upon request. Contact Sales to get started.

This guide describes how you can set up your Android project to use the TomTom 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 development environment meets the following requirements:

  • Android ABIs: arm64-v8a and x86_64.
  • 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 Meerkat Feature Drop | 2024.3.2 or higher.
  • JDK version 17.
  • Android Gradle plugin version 8.10.1.
  • Gradle version 8.14.1.

Project setup

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

  1. Create a new Android Studio project or open an existing one, and ensure Gradle is used in your project.
  2. 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. 
    1android {
    2    defaultConfig {
    3        minSdk = 26
    4        ndk {
    5            abiFilters += listOf("arm64-v8a", "x86_64")
    6        }
    7    }
    8}
  3. 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

  1. 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}

  2. Verify that everything works as expected by adding a Navigation SDK dependency to the build.gradle.kts file of your application module. For example, com.tomtom.sdk.navigation:navigation-online. Synchronize the project.

    val version = "1.26.2"
    implementation("com.tomtom.sdk.navigation:navigation-online:$version")

  3. Get your TomTom API key. To find out how, refer to the How to get a TomTom API key guide.

  4. 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

  5. Declare the tomtomApiKey variable within the build.gradle.kts file, outside of the android block.

    val tomtomApiKey: String by project

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

Build a simple navigation application

Use all the relevant Navigation SDK APIs and built-in UI components to build a navigation application:

Learn more

Here are some suggestions for other things you can do: