Quickstart
The Map Display module provides tools to use the TomTom map in iOS applications, and lets you add visual components to the map, such as routes and markers.
You can also control map interactions and the camera position.
Project setup
- Configure the project as described in the project setup guide.
- Add the
TomTomSDKMapDisplay
module to your project’sPodfile
1TOMTOM_SDK_VERSION = '0.28.2'23target 'YourAppTarget' do4 use_frameworks!5 pod 'TomTomSDKMapDisplay', TOMTOM_SDK_VERSION6end - Install the dependencies by executing the following commands in the project directory:
pod repo-art update tomtom-sdk-cocoapodspod install --repo-update
- Import the
TomTomSDKMapDisplay
framework:import TomTomSDKMapDisplay
Adding a map
The Map Display module provides several classes and protocols to work with the map:
MapView
- A class used to display the map in the view hierarchy. Use it to interact with the map UI components and adjust the camera.TomTomMap
- The entry point for methods related to the map.MapViewDelegate
- A delegate that reports when theTomTomMap
is ready to be used.MapOptions
- A class used to set the initial configuration of the map.
Initializing MapView
Before initializing
MapView
you have to assign your API key usingMapsDisplayService
.MapsDisplayService.apiKey = "YOUR_API_KEY"
- Add proper import of map display framework.
import TomTomSDKMapDisplay
- There are several ways to create a
MapView
object. One of them is to use the initializer without parameters. If you don’t need to customize the map, you can use the initializer with an auto layout. For a non-autolayout setup and additional customization, see the other initializers.let mapView = MapView() - Add the created
MapView
to theUIViewController
view and setup constraints.1view.addSubview(mapView)23mapView.translatesAutoresizingMaskIntoConstraints = false4NSLayoutConstraint.activate([5 view.leftAnchor.constraint(equalTo: mapView.leftAnchor),6 view.rightAnchor.constraint(equalTo: mapView.rightAnchor),7 view.topAnchor.constraint(equalTo: mapView.topAnchor),8 view.bottomAnchor.constraint(equalTo: mapView.bottomAnchor),9]) - Run the app. You should see the initialized map.
Getting the Map
When the map is fully initialized you can use the TomTomMap
object to interact with it. There are three ways to check whether the map is ready to be used.
- Using the
MapViewDelegate
protocol. An object conforming to the protocol receives a call from theMapView(MapView, Map)
method with the map as a parameter. To use delegate, do the following:- Adopt the
MapViewDelegate
in the class.1extension ViewController: MapViewDelegate {2 func mapView(_: MapView, onMapReady map: TomTomMap) {3 // Store the `Map` object if later map adjustments are necessary4 self.map = map5 }678 func mapView(_ mapView: MapView, onStyleLoad result: Result<StyleContainer, Error>) {9 // Based on `result` you can find out if default or style that you are trying to load succeed or failed.10 }11...12} - Set the delegate implementation to the
MapView.delegate
view.mapView.delegate = self
- Adopt the
- Assign a ((Map) → Void) closure to the
MapView.onMapReadyCallback
property.1mapView.onMapReadyCallback = { (_: TomTomMap) in2 /* YOUR CODE GOES HERE */3}
Configuring the map
The map can be customized during initialization or after creation by changing individual attributes of the Map
property:
- To initialize the map with custom parameters, create a
MapOptions
object and pass it toMapView
init(mapOptions:)
. See the following example. - You can set the configuration after initialization by accessing the
Map
property and modifying itsstyleMode
,styleContainer
,cameraOptions
, and other attributes defined in theMap
.
1let styleContainer = StyleContainer.defaultStyle2let 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: nil13)14let mapOptions = MapOptions(15 mapStyle: styleContainer,16 apiKey: "YOUR_API_KEY",17 cameraUpdate: cameraUpdate,18 cachePolicy: resourceCachePolicy,19 styleMode: .dark20)21mapView = MapView(mapOptions: mapOptions)
MapOptions properties
Property | required/optional | Description |
required | Maps API key. | |
optional |
| |
optional | Custom | |
optional | Custom map style provided as | |
optional | Provides an initial |
Performance optimization
Caching
To show online maps, the SDK needs to 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(TimeInterval, UInt)
. 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 forbid caching.