Developer
THIS SDK ISDEPRECATED.

We rolled out a new and better SDK for you.

CHECK IT OUT

Downloads

Project set up

To develop your own application with the Maps SDK, you need to make sure that the pre-requisites are in place and that you have added the Maps SDK as a dependency into your project. Follow the steps below and then you are ready to code! The Maps SDK for Android is compatible with Java and Kotlin.

Get the pre-requisites in place:

  • Android Studio IDE is installed (Android Studio).
  • Set up the application minimum API level to Android 4.4 "Kit Kat" (API Level 19) or higher.

Set up your project like this:

  1. Open the Android Studio IDE.
  2. Create a new project or open an existing one.

Add repositories to all projects to the root/build.gradle:

1allprojects {
2

3   repositories {
4      jcenter()
5      google()
6      maven {
7         url 'https://repositories.tomtom.com/artifactory/maps-sdk-legacy-android'
8      }
9   }
10}

Choose the Maps SDK modules for your app

Either independently include modules for Maps, Search, and/or Routing or all of them at once. You can do so by adding the Maps SDK modules to the AndroidManifest.xml and build.gradle.

Configuration for all Maps SDK modules

To include all of the Maps SDK modules in your app, modify AndroidManifest.xml and build.gradle

  • Key initialization Please use dedicated constructors/methods to directly initialize with the Service API Key taken from http://developer.tomtom.com. This approach is more thoroughly described in the modules' documentation pages.

  • Modify build.gradle (app/build.gradle)

    1//library required to display map
    2implementation("com.tomtom.online:sdk-maps:{libversion}")
    3

    4//library required for search
    5implementation("com.tomtom.online:sdk-search:{libversion}")
    6

    7//library required for routing
    8implementation("com.tomtom.online:sdk-routing:{libversion}")
    9

    10//library required for traffic
    11implementation("com.tomtom.online:sdk-traffic:{libversion}")
    12

    13//library required for geofencing
    14implementation("com.tomtom.online:sdk-geofencing:{libversion}")
    15

    16//extention library for map custom style and ui support
    17implementation("com.tomtom.online:sdk-maps-ui-extensions:{libversion}")
    18

    19//extention library for rx-java2
    20implementation("com.tomtom.online:sdk-maps-rx-extensions:{libversion}")
    21

    22//extention library for kotlin support
    23implementation("com.tomtom.online:sdk-maps-ktx-extensions:{libversion}")
    24

    25//extention library for displaying static map
    26implementation("com.tomtom.online:sdk-maps-static-image:{libversion}")
    27

    28//extention library for driving features
    29implementation("com.tomtom.online:sdk-maps-driving-extensions:{libversion}")

  • Enable Java 8 Support in build.gradle (app/build.gradle)

    1android {
    2    compileOptions {
    3        sourceCompatibility JavaVersion.VERSION_1_8
    4        targetCompatibility JavaVersion.VERSION_1_8
    5    }
    6}

  • Add MultiDex support if required, as described in MultiDex

Building and Launching

You can build separate APKs for different ABIs to reduce the size of an application. According to Android documentation: Build multiple APKs , just add this to your build.gradle file:

1android {
2  ...
3  splits {
4    abi {
5      enable true
6    }
7  }
8}

You can also reduce the application size with Android App Bundles.

Maps SDK Examples app

The Maps SDK Examples app is available in two flavors – Kotlin and Java.

Download and build the Maps SDK Examples app to see the key features of the Maps SDK.

Modify the source code to learn more about the SDK.

Speed up development by using the source code in your own app.

The Maps SDK Examples are hosted on github: https://github.com/tomtom-international/maps-sdk-for-android-examples.

git clone https://github.com/tomtom-international/maps-sdk-for-android-examples.git

This Maps SDK Examples app is provided by TomTom and subject to TomToms privacy policy at https://tomtom.com/privacy

Developers using TomTom SDKs and APIs in their apps similarly bear responsibility to adhere to the applicable privacy laws.

These Maps SDK Examples are provided as-is and shall be used internally, and for evaluation purposes only. Any other use is strictly prohibited.

Logging

TomTom SDK Log level

In TomTom we are constantly working on the quality of our products. That is why it is very important to have logs as detailed as possible for our support team to provide accurate help or bugfixes. The Maps SDK for Android has an advanced mechanism to gather and send logs to our support team. To enable logging and specify a log level please add the following code to your app:

Example:

1@Override
2public void onCreate() {
3    super.onCreate()
4    LogUtils.enableLogs(Log.VERBOSE);
  • android.util.Log.VERBOSE will print all logs from TomTom SDK.
  • android.util.Log.DEBUG will print debug logs from TomTom SDK.

Note: Logs from the SDK libraries are disabled by default.

Collecting logs

TomTom log

Logs from an application can be collected into a file on the SD card.

LogUtils.collectLogsToFile(logsFilePath);

A special permission should be added into your AndroidManifest.xml file to save logs on the SD card. For example:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

When the sdk-maps module is used, the problem with supporting runtime permissions is handled by the SDK with the following method:

1@Override
2public void onMapReady(@NonNull TomtomMap tomtomMap) {
3    tomtomMap.collectLogsToFile(SampleApp.LOG_FILE_PATH);
4}
1override fun onMapReady(tomtomMap: TomtomMap) {
2    tomtomMap.collectLogsToFile(SampleApp.LOG_FILE_PATH)
3}

Important: Since Android API level 23, it is required to ask the user for runtime permission to write into the SD card.

Register crash observer

Using the crash observer makes it possible to automate the process of preparing an email message with attached logs which were already collected and stored on the SD card. To do so, please register a crash handler with the following code. Crash observer doesn’t break your already-used handlers ( like Crashlitics).

LogUtils.registerCrashObserver(getApplicationContext(), Uri.parse("file://" + LOGCAT_PATH), CRASH_OBSERVER_EMAIL);

Bug report

To enable an advanced logging mechanism which collects detailed data from logcat like: threads, services, and phone states, please use the following code:

adb bugreport issue01

This produces an issue01.zip file.

Troubleshooting

Depending on your project configuration, some dependency conflicts may occur when adding the Maps SDK modules. Here you can find a list of possible issues and tips how to solve them:

  • FindBugs JSF305 conflict: Enforce Gradle to compile the fixed FindBugs version for all dependencies. Add the following lines to your app’s build.gradle:

    1android {
    2    configurations.all {
    3        resolutionStrategy.force 'com.google.code.findbugs:jsr305:3.0.2'
    4    }
    5}

  • MultiDex issues should be solved using Google instructions. However, see the following most popular solutions. Configure your app for MultiDex. Add the following lines to your app’s build.gradle:

    1android {
    2    defaultConfig {
    3        multiDexEnabled true
    4    }
    5}

    Add MultiDex support in your app’s build.gradle when minSdkVersion is set to 20 or lower:

    1dependencies {
    2    api 'com.android.support:multidex:1.0.1'
    3}

    Increase the java max heap size for dex support if required. Add the following lines to your app’s build.gradle:

    1android {
    2    dexOptions {
    3        javaMaxHeapSize "4g"
    4    }
    5}

  • R8 / ProGuard If you are using R8 or ProGuard add the options to your ProGuard file:

    1-repackageclasses com.tomtom.online.sdk.common.internal
    2-keep public class com.tomtom.online.sdk.common.** {
    3    public protected *;
    4}