Personal Data

VERSION 1.8.0
PUBLIC PREVIEW

To use the Maps SDK in your application you need to obtain a TomTom API key by following these instructions. Remember to keep your API key secure.

Introduction

The Personal Data modules provide easy and efficient access to a user’s personal data. This data encompasses home, work, favorite locations, and recent destinations. Based on their relevance, the user can designate these locations to search, routing, and navigation. These features are important for creating navigation applications that enhance the user experience.

By the end of this guide, you will be able to use the Personal Data modules to manage a user’s profile in your Android application, allowing for a more personalized and seamless navigation experience.

Project setup

The Personal Data functionality is divided into two modules:

  • The personal-data-api interface module
  • The personal-data implementation module.

Configure the project as described in the Project setup guide.

Then add the personal-data-api and personal-data module dependencies in the build.gradle.kts file of your application module and synchronize the project.

implementation("com.tomtom.sdk.personaldata:personal-data-api:1.8.0")
implementation("com.tomtom.sdk.personaldata:personal-data:1.8.0")

User profiles

To manage user profiles in your application, you must work with the PersonalData interface and its implementation. This provides you with methods for loading, storing, and clearing the user profile. It also allows you to get update notifications on changes to the user profile data.

The user data is represented in memory as a UserProfile object, containing the user’s personal locations, such as home, work, favorites, and recent destinations.

Note: Whenever you change the user profile data, you must store the user profile in order to persist the changes, otherwise they are saved only in memory and lost when the application is closed.

Working with offline personal data

First, create an instance of PersonalData using the personal data factory. You’ll need to specify a directory for storing the data.

Further, this is how can use the PersonalData instance to manage the user profile.

1 val personalData: PersonalData = PersonalDataFactory.create(context, File("path/to/personal/data"))
2
3 // Loading the user profile in memory.
4 var userProfile: UserProfile = personalData.loadUserProfile().fold(
5 ifSuccess = {
6 it
7 },
8 ifFailure = { failure ->
9 // There was an error loading the user profile; use an empty user profile instead.
10 UserProfile()
11 }
12 )
13
14 // Modifying the in-memory user profile.
15 userProfile.locations.create(
16 types = setOf(PersonalLocation.Type.Home),
17 place = Place(
18 coordinate = GeoPoint(
19 latitude = 52.373207,
20 longitude = 4.891391
21 ),
22 address = Address(
23 freeformAddress = "Royal Palace, Amsterdam, Netherlands"
24 )
25 ),
26 name = "Royal Home"
27 )
28
29 // Storing the user profile.
30 userProfile = personalData.storeUserProfile(userProfile).fold(
31 ifSuccess = {
32 it
33 },
34 ifFailure = { failure ->
35 // There was an error storing the user profile, use the previous user profile.
36 userProfile
37 }
38 )
39}

Personal locations

Personal locations refer to the user’s home, work, favorites, and recent destinations.

A personal location is represented by the PersonalLocation class, which contains the following useful properties:

  • id: A unique identifier for the location.
  • name: The personal name of the location.
  • types: A set of types for the location, such as Home, Work, Favorite, or Recent.
  • place: The place of the location, which includes information such as coordinates and address.
  • hasPrivateCharger: A boolean value indicating whether the location has an EV charger available for private use.

Note: Whenever you change the user profile data, you must store the user profile in order to persist the changes, otherwise they will be lost when the application is closed.

Adding personal locations

You can add personal locations in the UserProfile in-memory object by using the create method of UserLocations.

For example, you can add a favorite location to the user profile as follows:

1userProfile.locations.create(
2 types = setOf(PersonalLocation.Type.Favorite),
3 place = Place(
4 coordinate = GeoPoint(
5 latitude = 52.379015,
6 longitude = 4.900416
7 ),
8 address = Address(
9 freeformAddress = "Central Station, Amsterdam, Netherlands"
10 )
11 ),
12 name = "Train Station"
13)

Note: Whenever you change the user profile data, you must store the user profile in order to persist the changes, otherwise they are saved only in memory and lost when the application is closed.

Next steps

Since you have learned the basics of personal data management, here are recommendations for the next steps: