Personal Data
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 iOS application, allowing for a more personalized and seamless navigation experience.
Project setup
The Personal Data functionality is divided into two modules:
- The
TomTomSDKPersonalData
interface module. - The
TomTomSDKPersonalDataDefault
implementation module.
Configure the project according to the project setup guide and import the necessary frameworks using the following instructions, based on your preferred package manager:
Swift Package Manager
- Open your App’s target and navigate to General > Frameworks, Libraries, and Embedded Content.
- Add the following TomTomSDK libraries from the provided code snippet. Once the project is set up, import the mentioned frameworks into your code.
1import TomTomSDKCommon2import TomTomSDKPersonalData3import TomTomSDKPersonalDataDefault
CocoaPods
- Add the
TomTomSDKPersonalData
and theTomTomSDKPersonalDataDefault
module dependencies to your project’sPodfile
:1TOMTOM_SDK_VERSION = '0.67.0'23target 'YourAppTarget' do4 use_frameworks!5 pod 'TomTomSDKPersonalData', TOMTOM_SDK_VERSION6 pod 'TomTomSDKPersonalDataDefault', TOMTOM_SDK_VERSION7end - Install the dependencies by executing the following commands in the project directory:
pod repo-art update tomtom-sdk-cocoapodspod install --repo-update
- Import the following frameworks:
1import TomTomSDKCommon2import TomTomSDKPersonalData3import TomTomSDKPersonalDataDefault
User profiles
To manage user profiles in your application, you must work with the PersonalData
protocol 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
struct, containing the user’s personal locations, such as home, work, favorites, and recent destinations.
Note: Whenever you change the user profile data, you must use PersonalData.storeUserProfile(_:completion:)
method 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 PersonalDataFactory
. 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.
1let personalData = try PersonalDataFactory.create(2 with: "file/path/to/storage"3)45// Loading the user profile in memory.6var userProfile: UserProfile78do {9 userProfile = try personalData.loadUserProfile()10} catch {11 userProfile = UserProfile()12}1314// Modifying the in-memory user profile.15try userProfile.locations.create(16 types: [.favorite],17 place: Place(18 coordinate: CLLocationCoordinate2D(19 latitude: 52.373207,20 longitude: 4.89139121 ),22 address: Address(23 freeformAddress: "Royal Palace, Amsterdam, Netherlands"24 )25 ),26 name: "Royal Home"27)2829// Storing the user profile.30try personalData.storeUserProfile(userProfile)
Personal locations
Personal locations refer to the user’s home, work, favorites, and recent destinations.
A personal location is represented by the PersonalLocation
struct, which contains the following useful properties:
PersonalLocation.id
: A unique identifier for the location.PersonalLocation.name
: The personal name of the location.PersonalLocation.types
: A set of types for the location, such asPersonalLocation.Type.home
,PersonalLocation.Type.work
,PersonalLocation.Type.favorite
, orPersonalLocation.Type.recent
.PersonalLocation.place
: The place of the location, which includes information such as coordinates and address.PersonalLocation.hasPrivateCharger
: A boolean value indicating whether the location has an EV charger available for private use.
The user profile ensures that PersonalLocation.Type.home
and PersonalLocation.Type.work
locations are unique locations. The UserLocations
struct automatically handles this constraint, ensuring at most one PersonalLocation.Type.home
and one PersonalLocation.Type.work
location are set at any time. If a new PersonalLocation.Type.home
or PersonalLocation.Type.work
location is added or an existing location is updated to have one of these types, any previous location having this same type will have it removed in order to maintain the constraint.
The uniqueness of PersonalLocation.Type.home
and PersonalLocation.Type.work
locations is maintained through the use of methods like UserLocations.create(types:place:name:hasPrivateCharger:)
or UserLocations.update(location:types:)
. These methods automatically handle the enforcement of this rule, ensuring that you don’t need to use additional logic to maintain their uniqueness.
Note: Whenever you change the user profile data, you must use PersonalData.storeUserProfile(_:completion:)
method 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 UserLocations.create(types:place:name:hasPrivateCharger:)
method.
For example, you can add a favorite location to the user profile as follows:
1try userProfile.locations.create(2 types: [.favorite],3 place: Place(4 coordinate: CLLocationCoordinate2D(5 latitude: 52.379015,6 longitude: 4.9004167 ),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 use PersonalData.storeUserProfile(_:completion:)
method 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: