Configuring the map

VERSION 0.67.0

The Map Display module allows you to show the TomTom map in your iOS application. To meet your use case requirements, you can apply initial settings during initialization using MapOptions. However, the map configuration can also be changed during runtime using the TomTomMap object.

Import the following frameworks to continue with this guide:

import CoreLocation
import TomTomSDKMapDisplay

Initializing the map in code

The map can be customized during initialization or after by changing individual attributes of the TomTomMap property:

Before initializing the map with custom parameters, you should change your MapView object type from var to let to make it mutable.
To initialize the map with custom parameters, create a MapOptions object and pass it to the MapView MapView.init(mapOptions:). This is demonstrated in the following example.
You can set the configuration after initialization by accessing the TomTomMap property and modifying its MapActions.styleMode, MapActions.styleContainer, CameraActions.applyCamera(_:animationDuration:completion:), and other attributes and methods defined in the TomTomMap.

1let styleContainer = StyleContainer.defaultStyle
2let amsterdam = CLLocationCoordinate2D(latitude: 52.3764527, longitude: 4.9062047)
3let resourceCachePolicy = OnDiskCachePolicy.cache(
4    duration: Measurement.tt.hours(10),
5    maxSize: Measurement.tt.megabytes(200)
6)
7let cameraUpdate = CameraUpdate(
8    position: amsterdam,
9    zoom: 10.0,
10    tilt: 45,
11    rotation: 0,
12    positionMarkerVerticalOffset: nil
13)
14let mapOptions = MapOptions(
15    mapStyle: styleContainer,
16    apiKey: "YOUR_TOMTOM_API_KEY",
17    cameraUpdate: cameraUpdate,
18    cachePolicy: resourceCachePolicy,
19    styleMode: .dark
20)
21mapView = MapView(mapOptions: mapOptions)

MapOptions properties

Property	Required/optional	Description
`MapOptions.apiKey`	Required	Maps API key.
`MapOptions.cameraUpdate`	Optional	`CameraUpdate` for a map. Provides position, rotation, tilt, and zoom of the camera. More information is found in the Camera and animations guide.
`MapOptions.cachePolicy`	Optional	Custom `OnDiskCachePolicy` used for caching style and tiles. The `OnDiskCachePolicy.default` configuration sets the cache for 24 hours and a maximum of 100MB. If you do not want to cache any information about the map, use the `OnDiskCachePolicy.noCaching` property.
`MapOptions.mapStyle`	Optional	Custom map style provided as a `StyleContainer`. More information about map styling can be found in the Styling the map guide.
`MapOptions.styleMode`	Optional	Provides an initial `StyleMode` of the map. The default is the TomTom light style. You can read more about `StyleMode` in the Styling the map guide.

Performance optimization

Caching

To show online maps, the SDK must download data over the network (e.g., tiles), and store the already-downloaded data in the file system. Every iOS application has different requirements for network and disk usage, just as it does for what objects are displayed (e.g., roads). And it’s up to the app developer to find the best strategy to use those resources. Since resource demands can vary, the Map SDK provides different caching policies to help to optimize performance for your specific use case.

Map caching can be configured using the OnDiskCachePolicy enum, which you need to provide to the MapOptions object. The Map SDK caches:

Map tiles
Styles
Sprites
Fonts

If there is no need to cache anything from the map, use the OnDiskCachePolicy.noCaching value. Otherwise, custom settings can be applied using the OnDiskCachePolicy.cache(duration:maxSize:). It requires two parameters:

Maximum time that fetched resources can stay in the cache.
Maximum size of the cache, in megabytes.

By default, the cache size limit is set to 100MB and the lifetime duration to 24 hours.

The server can influence the way caching operates and, for example, can forbid caching.

Next steps

Since you have learned how to configure a map, here are recommendations for the next steps: