Offline Map
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.com2login <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. Thepod 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 disabled6)
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 theOnboardStyleURLProvider
class from which you can access onboard resources.1let mainStyle: StyleDefinition = .custom(2 style: OnboardStyleURLProvider.browsingLightStyleURL,3 layerMapping: OnboardStyleURLProvider.layerMappingURL4)5let darkStyle: StyleDefinition = .custom(6 style: OnboardStyleURLProvider.browsingDarkStyleURL,7 layerMapping: OnboardStyleURLProvider.layerMappingURL8)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:
1styles2│3└─onboard_layer_mapping.json4│5└─dark6│ │7│ └─sprite@2x.json8│ │9│ └─sprite@2x.png10│ │11│ └─style-browsing.json12│ │13│ └─style-driving.json14│15└─light16 │17 └─sprite@2x.json18 │19 └─sprite@2x.png20 │21 └─style-browsing.json22 │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)