Quickstart

VERSION 0.45.0

Offline functionality for the Maps and Navigation SDKs for iOS is only available upon request. Contact us to get started.

The Navigation SDK offers a complete navigation experience, including the ability to work with offline maps. Offline maps allow users to search for destinations, plan routes, and navigate even without an internet connection.

The offline maps are divided into map regions. A map region can be any geographical area: a city such as Amsterdam, an area inside a country such as North Holland, a country such as The Netherlands, or a region such as Benelux.

You can choose to update or install any map region so that the data is available to other components of the SDK for offline use. When used offline, the Navigation SDK only uses data from the map regions that are installed on the device.

In this guide, we will walk you through the process of setting up and using offline maps in your application.

Prerequisites

Before proceeding, ensure that you have the following:

Offline setup package: This package should contain a map, a keystore, a map access license token, and an API key for map updates.
Project setup: Configure your project according to the instructions provided in the Project setup guide.

Getting access

Because the repository for Offline SDK is private, you will need to contact us to get access.
Once you have obtained access, go to repositories.tomtom.com and log in with your account. Expand the user menu in the top-right corner, and select "Edit profile" → "Generate an Identity Token". Copy the generated token and use it to specify your credentials in the ~/.netrc file. If the ~/.netrc file doesn’t exist, create one and add the following entries:
- Replace the USERNAME_PLACEHOLDER with the login username or email you use for repositories.tomtom.com.
- Replace the IDENTITY_TOKEN_PLACEHOLDER with the generated identity token.
- Add a new line to the end of the ~/.netrc file to avoid parsing errors.
```
1machine repositories.tomtom.com
2login <USERNAME_PLACEHOLDER>
3password <IDENTITY_TOKEN_PLACEHOLDER>
```

Adding dependencies

Swift Package Manager

Offline maps require access to the tomtom-sdk-spm-offline package.

Here’s how to add this package to your project:

Click "File" > "Add Packages… / Add Package Dependencies…" in XCode.
In the "Enter Package URL" textbox, enter the URL for tomtom-sdk-spm-offline package.
Set the "Dependency Rule" to "Exact Version."
Ensure that you’ve selected the appropriate project where you want to add this dependency and click "Add Package".
For test purposes, choose TomTomSDKDataManagementOffline from the Offline product list.
Once the package is successfully resolved and added to your project, you can use this package by importing its modules into your Swift files:
```
import TomTomSDKDataManagementOffline
```

CocoaPods

Offline maps require access to the TomTomSDKDataManagementOffline module. To update the offline maps, use the TomTomSDKNDSStoreUpdater module.

Here’s how to add them to your project:

Add the TomTomSDKDataManagementOffline and TomTomSDKNDSStoreUpdater modules to your project’s Podfile.
```
1TOMTOM_SDK_VERSION = '0.45.0'
2
3target 'YourAppTarget' do
4  use_frameworks!
5  pod 'TomTomSDKDataManagementOffline', TOMTOM_SDK_VERSION
6  pod 'TomTomSDKNDSStoreUpdater', TOMTOM_SDK_VERSION
7end
```
Update and install the dependencies by executing the following command in the project directory:
```
pod install --repo-update
```
Once the pod install command is successfully finished, you should have the .xcworkspace file in the project directory. Open that .xcworkspace file to start working on the Xcode project.

Loading the offline map

The offline map must be compliant with the Navigation Data Standard version 2.4.6.

To use the offline map, you must have a map on the device and instantiate the NDSStore object that loads it. For this, you need the TomTomSDKDataManagementOffline dependency. It can then be used by other components of the SDK to provide their features completely offline.

1let ndsStore = try NDSStore(configuration: NDSStoreConfiguration(
2    mapDataPath: "path/to/map_directory/",
3    keystorePath: "path/to/keystore",
4    accessPermit: .mapLicense("your map license")
5))

To access a specific offline map, create only one instance of NDStore. Creating multiple instances for the same map can lead to unexpected behavior.

The NDSStoreConfiguration.mapDataPath in the initializer must point to the directory where the offline map is stored, and which contains the ROOT.NDS file. The directory must be an accessible location on the device. The directory must be writable if map updates are used.

For encrypted maps, the initializer must contain:

NDSStoreConfiguration.keystorePath - The file path to the keystore SQLite file used to decrypt the map.
NDSStoreConfiguration.accessPermit - A valid map license token for offline map functionality.

The keystore file and license token are supplied with the map.

As you prepare to use the offline map, you must add the following fonts to the Xcode project:

Noto-Bold.ttf
Noto-Medium.ttf
Noto-Regular.ttf
NotoSans-MediumItalic.ttf
NotoSans-RegularItalic.ttf

These fonts can be downloaded using: this url.

These fonts only support latin characters. In case you would like to support non-latin characters, you will need to add the appropriate NotoSans fonts.

Downloading map contents around the specified location

The offline map included in the setup package contains only metadata and does not include pre-installed map regions. Therefore, it is necessary to install map regions before utilizing search, display, routing, or navigation functionalities.

To enable automatic map updates around the specified location, follow these steps:

Add the TomTomSDKNDSStoreUpdater framework as a dependency to your application and import it.
Create an NDSStoreUpdateConfig with the NDSStoreUpdateConfig.AutomaticUpdatesConfiguration.relevantRegionsEnabled property set to true:
```
1let updateConfigWithRelevantUpdates = NDSStoreUpdateConfig(
2    updateStoragePath: "path/to/directory/to/download/updates/",
3    persistentStoragePath: "path/to/directory/for/persistence/",
4    automaticUpdatesConfiguration: NDSStoreUpdateConfig.AutomaticUpdatesConfiguration(
5        relevantRegionsEnabled: true
6    )
7)
```
Instantiate the NDSStoreUpdater using the configuration from the previous step and the previously created NDSStore instance.
```
1let ndsStoreUpdater = try NDSStoreUpdater(
2    config: updateConfig, ndsStore: ndsStore
3)
```

Make sure to create only one instance of NDSStoreUpdater. Creating multiple instances for the same map can lead to unexpected behavior.

Update the position by passing the location to the NDSStoreUpdater.
```
let amsterdam = CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070)
ndsStoreUpdater.updatePosition(amsterdam)
```

The NDSStoreUpdater will download the relevant map regions around the specified location in the background.

Utilizing the NDSStore

Now that the NDSStore is created and map contents are successfully downloaded, you can use it with other SDK components. For example, you can create a route planner:

let routePlanner = try OfflineRoutePlanner(store: ndsStore)

With the route planner, you can plan routes by providing the desired itinerary:

1let amsterdam = ItineraryPoint(coordinate: CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070))
2let rotterdam = ItineraryPoint(coordinate: CLLocationCoordinate2D(latitude: 51.926517, longitude: 4.462456))
3let routePlanningOptions = try RoutePlanningOptions(itinerary: Itinerary(origin: amsterdam, destination: rotterdam))
4routePlanner.planRoute(options: routePlanningOptions, onRouteReady: nil, completion: { result in
5    switch result {
6    case let .success(routePlanningResponse):
7        let route = routePlanningResponse.routes?.first
8    // Your code goes here
9    case let .failure(error):
10        print(error.localizedDescription)
11        // Your code goes here
12    }
13})

Next steps

You have successfully set up and utilized offline maps with the Navigation SDK. To further enhance your offline map implementation, consider exploring the following topics:

Visualizing an offline map: Learn more about how to visualize an offline map.
Offline Map Setup: Learn more about advanced configuration options and customization possibilities for offline maps.
Manual Map Management: Learn more about manual operations on map regions and how to monitor changes in map structure and state.
Adding traffic support: Learn more about how to include live traffic information to your map visualization.

By diving deeper into these areas, you can unlock the full potential of offline maps in your application.