Offline Map

VERSION 0.2.3404

Offline functionality for Maps SDK for iOS is only available upon request. Contact us to get started.

This tutorial shows how to build a simple navigation application that works without requiring internet connectivity. It uses the TomTom Maps and Navigation SDKs for iOS. All components are in dedicated modules, available as separate Cocoapods. The engines implement the same interface as their online counterparts but work with an offline map.

Getting started

The Navigation SDK for iOS is only available upon request. Contact us to get started.

Install Xcode if you don’t already have it.
Create a new project or open an existing one. The application deployment target has to be set to at least 13.0.
Install Cocoapods on your computer.
```
sudo gem install cocoapods
```
Install cocoapods-art tool on your computer.
```
sudo gem install cocoapods-art to install cocoapods-art
```
Because the repository for Navigation 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 your token and put it, together with your login, in ~/.netrc. If the file doesn’t exist, create one and add the following entry:
```
1machine repositories.tomtom.com
2login <YOUR_LOGIN>
3password <YOUR_TOKEN>
```
Add a reference to the cocoapods-art repository:
```
pod repo-art add tomtom-sdk-cocoapods "https://repositories.tomtom.com/artifactory/api/pods/cocoapods"
```
Then create a Podfile in the project folder. The pod init command in the project folder can generate a basic podfile.
At the top of the Podfile add the source of the SDK Cocoapods.
```
1plugin 'cocoapods-art', :sources => [
2   'tomtom-sdk-cocoapods'
3]
```

Providing access to an 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. This object then lets you manage the map regions of the loaded map. It can then be used by other components of the SDK to provide their features completely offline.

1let store = NDSStore(
2    mapDataPath: "path/to/map_directory/",
3    keystorePath: "path/to/keystore",
4    keystorePassword: "password",
5    ndsStoreUpdateConfig: nil // Map updates disabled
6)

The 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 configured.

For encrypted maps, the initializer must contain:

keystorePath - The file path to the keystore SQLite file used to decrypt the map.
keystorePassword - The password to decrypt the keystore, if it is encrypted.

Lastly, the NDSStoreUpdateConfig object configures parameters related to updates of the offline map. It is not required to do this.

Displaying a map

Once access to an offline map has been setup, it needs to be displayed. This is achieved by creating an instance of the MapDisplayOnboardTileDataProvider class, which is part of the TomTomSDKMapDisplayDataProviderOffline module. Use the newly created NDSStore object, from the previous section, as a parameter.

1let store = NDSStore(
2    mapDataPath: "mapDataPath",
3    keystorePath: "keystorePath"
4)
5tileDataProvider = try? MapDisplayOnboardTileDataProvider(store: store!)
6onboardDataProvider = OnboardDataProvider(tileDataProvider: tileDataProvider)

There are two options to style the offline map:

Style the map using the style provider included in the SDK. The TomTomSDKStyleProviderOffline module contains the OnboardStyleURLProvider class from which you can access onboard resources.
```
1let mainStyle: StyleDefinition = .custom(
2    style: OnboardStyleURLProvider.browsingLightStyleURL,
3    layerMapping: OnboardStyleURLProvider.layerMappingURL
4)
5let darkStyle: StyleDefinition = .custom(
6    style: OnboardStyleURLProvider.browsingDarkStyleURL,
7    layerMapping: OnboardStyleURLProvider.layerMappingURL
8)
9onboardStyleContainer = StyleContainer(
10    mainStyle: mainStyle,
11    darkStyle: darkStyle,
12    bundle: OnboardStyleURLProvider.resourcesBundle!
13)
```
Create your own resources and put them into a separate bundle. This bundle should contain:
- mapbox style file for different modes
- sprite and sprite atlasses
- layer mapping JSON file

Create a StyleContainer with URLs pointing to the local resources and bundle. Include the fonts used by the Mapbox style file in the main bundle.

Below is an example of a resource bundle folder structure:

1styles
2│
3└─onboard_layer_mapping.json
4│
5└─dark
6│  │
7│  └─sprite@2x.json
8│  │
9│  └─sprite@2x.png
10│  │
11│  └─style-browsing.json
12│  │
13│  └─style-driving.json
14│
15└─light
16  │
17  └─sprite@2x.json
18  │
19  └─sprite@2x.png
20  │
21  └─style-browsing.json
22  │
23  └─style-driving.json

Once you have an onboard tile provider and style container, create a TomTomMapView object with MapOptions. Note, the option to cache is not required for offline as the map is stored on the device.

1let mapOptions = MapOptions(
2    mapStyle: onboardStyleContainer,
3    apiKey: "YOUR_API_KEY",
4    cachePolicy: .noCaching,
5    styleMode: .main,
6    dataProviders: [onboardDataProvider]
7)
8mapView = MapView(mapOptions: mapOptions)