Offline Map

VERSION 0.28.2

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 map application that works without requiring internet connectivity. It uses the TomTom Maps 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

Configure the project as described in the project setup guide.

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 ndsStore = NDSStore(
2    mapDataPath: "path/to/map_directory/",
3    keystorePath: "path/to/keystore",
4    accessPermit: .mapLicense("your map license"),
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:

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

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

Lastly, the NDSStoreUpdateConfig object configures parameters related to updates of the offline 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-Regular.ttf

These fonts can be downloaded using: this url.

Displaying a map

Once access to an offline map has been set up, it needs to be displayed. You can display the offline map by creating an instance of the MapDisplayDataProvider protocol using the OfflineDataProviderFactory.createOfflineDataProvider method. This is a 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)
5offlineDataProvider = try? OfflineTileDataProviderFactory.createOfflineTileDataProvider(store: store!)

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: OfflineStyleURLProvider.browsingLightStyleURL,
3    layerMapping: OfflineStyleURLProvider.layerMappingURL
4)
5let darkStyle: StyleDefinition = .custom(
6    style: OfflineStyleURLProvider.browsingDarkStyleURL,
7    layerMapping: OfflineStyleURLProvider.layerMappingURL
8)
9offlineStyleContainer = StyleContainer(
10    mainStyle: mainStyle,
11    darkStyle: darkStyle,
12    bundle: OfflineStyleURLProvider.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.

The following is an example of a resource bundle directory 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 data 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: offlineStyleContainer,
3    apiKey: "YOUR_API_KEY",
4    cachePolicy: .noCaching,
5    styleMode: .main,
6    dataProviders: [offlineDataProvider]
7)
8mapView = MapView(mapOptions: mapOptions)