Step-by-step guide

VERSION 2.1.2

This guide helps you migrate your existing TomTom’s Maps SDK and Navigation SDK projects from version 1 to version 2. Version 2 introduces significant improvements and architectural changes which require updates to your project configuration and code.

Overview of Changes

Version 2 introduces several major changes:

Module restructuring: Modules have been reorganized and renamed for better clarity and ease of integration.
Product flavors: Added support for product flavors in the SDK artifacts.
Android SDK updates: Switch compileSdk from Android API level 34 to 35.
Package name changes: Some classes have been moved to a different package.
Permission updates: Some modules require additional permissions.
TomTom Orbis Maps: SDKs are moving from TomTom Maps to TomTom Orbis Maps.

Breaking Changes

Module Restructuring

The SDK has been reorganized to improve clarity and reduce complexity. You’ll need to update the references to the SDK modules in your build script or catalogue.

The following examples show how to migrate your dependency declarations from version 1 to version 2. Replace your existing version 1 dependencies with their corresponding version 2 equivalents:

Common Modules

1
// Version 1
2
implementation("com.tomtom.sdk.common:android:1.26.4")
3
implementation("com.tomtom.sdk.common:metadata:1.26.4")
4

5
// Version 2
6
implementation("com.tomtom.sdk.common:core:2.1.2")

Data Management

1
// Version 1
2
implementation("com.tomtom.sdk.datamanagement:nds-store:1.26.4")
3
implementation("com.tomtom.sdk.datamanagement:nds-store-updater:1.26.4")
4
implementation("com.tomtom.sdk.datamanagement:navigation-tile-store:1.26.4")
5
implementation("com.tomtom.sdk.datamanagement:navigation-data-store-hybrid:1.26.4")
6

7
// Version 2
8
implementation("com.tomtom.sdk.datamanagement:data-store:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.mapreferences:model:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.datamanagement:map-references:2.1.2")

Map Display

For a comprehensive guide on setting up and using Map Display in version 2, see the Map Display Quickstart guide .

1
// Version 1
2
implementation("com.tomtom.sdk.maps:map-display-api:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.maps:map-display-common:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.maps:map-display:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.maps:map-display-standard:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.maps:style-provider-offline:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.maps:map-display-style-provider-offline:2.1.2")

Maps Data Providers

1
// Version 1
2
implementation("com.tomtom.sdk.maps:data-provider:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.maps:map-tile-store-common:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.maps:map-data-provider:1.26.4")
3
implementation("com.tomtom.sdk.maps:map-data-store-online:1.26.4")
4

5
// Version 2
6
implementation("com.tomtom.sdk.maps:map-tile-store:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.maps:traffic-data-provider:1.26.4")
3
implementation("com.tomtom.sdk.maps:hybrid-data-provider:1.26.4")
4
implementation("com.tomtom.sdk.maps:data-provider-offline:1.26.4")
5
implementation("com.tomtom.sdk.maps:map-tile-store-offline:1.26.4")
6
implementation("com.tomtom.sdk.maps:map-tile-store-hybrid:1.26.4")
7

8
// Version 2
9
implementation("com.tomtom.sdk.maps:map-tile-store-navigation:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.navigation:navigation-engines:1.26.4")
3
implementation("com.tomtom.sdk.navigation:navigation-hybrid:1.26.4")
4
implementation("com.tomtom.sdk.navigation:navigation-offline:1.26.4")
5
implementation("com.tomtom.sdk.navigation:navigation-online:1.26.4")
6
// All other com.tomtom.sdk.navigation:navigation-* modules
7

8
// Version 2
9
implementation("com.tomtom.sdk.navigation:navigation:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.navigation:service:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.navigation:ui:2.1.2")

Routing

1
// Version 1
2
implementation("com.tomtom.sdk.routing:common:1.26.4")
3
implementation("com.tomtom.sdk.routing:model:1.26.4")
4
implementation("com.tomtom.sdk.routing:route-planner:1.26.4")
5
implementation("com.tomtom.sdk.routing:route-planner-api-coroutines:1.26.4")
6

7
// Version 2
8
implementation("com.tomtom.sdk.routing:routing-common:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.routing.range:range-calculator:1.26.4")
3
implementation("com.tomtom.sdk.routing:range-calculator-offline:1.26.4")
4
implementation("com.tomtom.sdk.routing:range-calculator-online:1.26.4")
5

6
// Version 2
7
implementation("com.tomtom.sdk.routing:range-calculator:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.routing:route-planner-offline:1.26.4")
3
implementation("com.tomtom.sdk.routing:route-planner-online:1.26.4")
4
implementation("com.tomtom.sdk.routing:route-planner-hybrid:1.26.4")
5

6
// Version 2
7
implementation("com.tomtom.sdk.routing:route-planner:2.1.2")

Search

1
// Version 1
2
implementation("com.tomtom.sdk.search:search:1.26.4")
3
implementation("com.tomtom.sdk.search:reverse-geocoder:1.26.4")
4
implementation("com.tomtom.sdk.search:dynamic-data:1.26.4")
5
implementation("com.tomtom.sdk.search:structured-search:1.26.4")
6

7
// Version 2
8
implementation("com.tomtom.sdk.search:search-common:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.search:search-online:1.26.4")
3
implementation("com.tomtom.sdk.search:search-offline:1.26.4")
4
implementation("com.tomtom.sdk.search:search-hybrid:1.26.4")
5
implementation("com.tomtom.sdk.search:structured-search-offline:1.26.4")
6
implementation("com.tomtom.sdk.search:dynamic-data-online:1.26.4")
7
implementation("com.tomtom.sdk.search:search-custom-data-online:1.26.4")
8

9
// Version 2
10
implementation("com.tomtom.sdk.search:search:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.search:reverse-geocoder-online:1.26.4")
3
implementation("com.tomtom.sdk.search:reverse-geocoder-offline:1.26.4")
4
implementation("com.tomtom.sdk.search:reverse-geocoder-hybrid:1.26.4")
5

6
// Version 2
7
implementation("com.tomtom.sdk.search:reverse-geocoder:2.1.2")

Traffic

1
// Version 1
2
implementation("com.tomtom.sdk.traffic:client:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.traffic:traffic-client:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.traffic:traffic-client-api:1.26.4")
3
implementation("com.tomtom.sdk.traffic:model:1.26.4")
4

5
// Version 2
6
implementation("com.tomtom.sdk.traffic:traffic-common:2.1.2")

Safety Locations

1
// Version 1
2
implementation("com.tomtom.sdk.safetylocations:safetylocations-online:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.safetylocations:safetylocations:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.safetylocations:safetylocations-model:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.safetylocations:safetylocations-common:2.1.2")

Hazards

1
// Version 1
2
implementation("com.tomtom.sdk.hazards:hazards-online:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.hazards:hazards:2.1.2")

1
// Version 1
2
implementation("com.tomtom.sdk.hazards:hazards-model:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.hazards:hazards-common:2.1.2")

Personalization

1
// Version 1
2
implementation("com.tomtom.sdk.personaldata:personal-data-api:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.personaldata:personal-data-common:2.1.2")

Vehicle

1
// Version 1
2
implementation("com.tomtom.sdk.vehicle:model:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.vehicle:vehicle-common:2.1.2")

Text-to-Speech

1
// Version 1
2
implementation("com.tomtom.sdk:tts-engine-api:1.26.4")
3
implementation("com.tomtom.sdk:tts-engine-android:1.26.4")
4

5
// Version 2
6
implementation("com.tomtom.sdk:tts:2.1.2")

Product Flavors Configuration

Version 2 introduces product flavors to better organize SDK variants. You must add a configuration to your app’s build script.

The Extended flavor of Maps and Navigation SDK for Android is only available upon request. Contact us to get started.

1
android {
2
    defaultConfig {
3
        missingDimensionStrategy("tomtom-sdk-version", "complete")
4
    }
5
}

Android Compile SDK Update

Update your app’s compileSdk version to Android API level 35 to ensure compatibility with the SDK:

1
android {
2
    compileSdk = 35
3
}

Package Name Changes

Several classes have moved to different packages:

com.tomtom.sdk.common.android.LocationMapper

1
// Version 1
2
import com.tomtom.sdk.common.android.LocationMapper
3

4
// Version 2
5
import com.tomtom.sdk.location.android.LocationMapper

Additionally, update the dependency for LocationMapper:

1
// Version 1 - was in common module
2
implementation("com.tomtom.sdk.common:android:1.26.4")
3

4
// Version 2 - moved to location module
5
implementation("com.tomtom.sdk.location:provider-android:2.1.2")

com.tomtom.sdk.mapreferences.*

1
// Version 1
2
import com.tomtom.sdk.mapreferences.MapId
3
import com.tomtom.sdk.mapreferences.MapPosition
4
import com.tomtom.sdk.mapreferences.MapReferences
5
import com.tomtom.sdk.mapreferences.RegionId
6

7
// Version 2
8
import com.tomtom.sdk.datamanagement.mapreferences.MapId
9
import com.tomtom.sdk.datamanagement.mapreferences.MapPosition
10
import com.tomtom.sdk.datamanagement.mapreferences.MapReferences
11
import com.tomtom.sdk.datamanagement.mapreferences.RegionId

No changes to the artifact name.

Permission updates

As of SDK version 2 the com.tomtom.sdk.navigation:ui and com.tomtom.sdk.search:ui modules are deprecated. For more information see the release notes .

If you’re using the Navigation UI module, you’ll need to add new permissions to your AndroidManifest.xml. These permissions are required for the navigation service to run in the foreground and display notifications to users:

1
<!-- Add these permissions to your AndroidManifest.xml -->
2
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
3
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Also note the module relocation from the service module to the ui module:

1
// Version 1
2
implementation("com.tomtom.sdk.navigation:service:1.26.4")
3

4
// Version 2
5
implementation("com.tomtom.sdk.navigation:ui:2.1.2")

TomTom Orbis Maps

APIs launching with version 2 use the TomTom Orbis Maps for all SDK operations. This provides improved performance, better data quality, and enhanced features compared to the previous TomTom Maps services. If your app was previously using the TomTomOrbisMapFeature feature toggle in public preview, your code will need to be modified to migrate to the new APIs.

Migrating from TomTomOrbisMapFeature

If your app was previously using the TomTomOrbisMapFeature feature toggle:

Remove the feature toggle from your code

1
// Remove the following line
2
FeatureToggleController.enable(TomTomOrbisMapFeature)

Update service initialization to use the new APIs (examples below)

TomTomSdk initialization

The TomTom Maps and Navigation SDK is now handled through a single entry point: TomTomSdk. It supports Online-only user experience and its configuration is handled through TomTomSdk.

The following snippets require to initialize TomTomSdk before using it. Please, refer to the Navigation SDK Initialization Guide guide on how to initialize it.

Search Migration

Identify uses of OnlineSearch.create factory function

1
search = OnlineSearch.create(context = this, BuildConfig.TOMTOM_API_KEY)

Substitute them with the corresponding new API:

1
search = TomTomSdk.createSearch()

Reverse Geocoder Migration

Identify uses of OnlineReverseGeocoder.create factory function

1
reverseGeocoder = OnlineReverseGeocoder.create(
2
    context = this,
3
    apiKey = BuildConfig.TOMTOM_API_KEY,
4
)

Substitute them with the corresponding new API:

1
reverseGeocoder = TomTomSdk.createReverseGeocoder()

Routing Migration

Identify uses of OnlineRoutePlanner.create factory function

1
routePlanner = OnlineRoutePlanner.create(
2
    context = this,
3
    apiKey = BuildConfig.TOMTOM_API_KEY,
4
)

Substitute them with the corresponding new API:

1
routePlanner = TomTomSdk.createRoutePlanner()

Identify uses of OnlineTomTomNavigationFactory.create factory function

1
navigation = OnlineTomTomNavigationFactory.create(
2
    Configuration(
3
        context = this,
4
        navigationTileStore = navigationTileStore,
5
        locationProvider = locationProvider,
6
        routePlanner = routePlanner,
7
    ),
8
)

Substitute them with the corresponding new API:

1
navigation = TomTomSdk.navigation

Map Display Changes

No code changes are required. Map Display will automatically use TomTom Orbis Maps in version 2.