Quickstart

VERSION 0.2.1455
PUBLIC PREVIEW

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 set up

  1. Get your TomTom API key from the Developer Portal. Instructions to request and use the TomTom API key can be found in the TomTom API key user guide.

  2. Configure the project as described in the project setup guide.

  3. Add the Map Display module dependency in the Podfile and install it by executing the pod install command.

    1SDK_VERSION = '{version}'
    2
    3target 'YourAppTarget' do
    4 use_frameworks!
    5 pod 'TomTomSDKMapsDisplay', SDK_VERSION
    6end

Adding a map

The Map Display module provides several classes and protocols to work with the map:

  • TomTomMapView - A class used to display the map in the view hierarchy. Use it to interact with map UI components (link to UI component guide) and adjust the camera (link to Camera guide).
  • TomTomMap - The entry point for methods related to the map.
  • TomTomMapViewDelegate - A delegate that reports when the TomTomMap is ready to be used.
  • MapOptions - A class used to set the initial configuration of the map.

Before you use a map in the project, add the TomTomSDKMapsDisplay dependency in your Podfile.

1target 'YourAppTarget' do
2 use_frameworks!
3 pod 'TomTomSDKMapsDisplay'
4end

Initializing TomTomMapView

Before initializing TomTomMapView you have to assign your API key using MapsDisplayService.

MapsDisplayService.mapsKey = "YOUR_API_KEY"
  1. Add proper import of map display framework.

    import TomTomSDKMapsDisplay
  2. There are several ways to create a TomTomMapView 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 tomTomMapView = TomTomMapView()
  3. Add the created TomTomMapView to the UIViewController view and setup constraints.

    1view.addSubview(tomTomMapView)
    2
    3tomTomMapView.translatesAutoresizingMaskIntoConstraints = false
    4NSLayoutConstraint.activate([
    5 view.leftAnchor.constraint(equalTo: tomTomMapView.leftAnchor),
    6 view.rightAnchor.constraint(equalTo: tomTomMapView.rightAnchor),
    7 view.topAnchor.constraint(equalTo: tomTomMapView.topAnchor),
    8 view.bottomAnchor.constraint(equalTo: tomTomMapView.bottomAnchor),
    9])
  4. Run the app. You should see the initialized map.


Getting the TomTomMap

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 TomTomMapViewDelegate protocol. An object conforming to the protocol receives a call from the tomTomMapView(TomTomMapView, TomTomMap) method with the map as a parameter. To use delegate, do the following:
    1. Adopt the TomTomMapViewDelegate in the class.
      1extension ViewController: TomTomMapViewDelegate {
      2 func tomTomMapView(_: TomTomMapView, onMapReady map: TomTomMap) {
      3 // Store the `TomTomMap` object if later map adjustments are necessary
      4 tomTomMap = map
      5 }
      6...
      7}
    2. Set the delegate implementation to the TomTomMapView.delegate view.
      tomTomMapView.delegate = self
  • Assign a ((TomTomMap) → Void) closure to the TomTomMapView.mapReady property.
    1tomTomMapView.mapReady = { (_: TomTomMap) in
    2 /* YOUR CODE GOES HERE */
    3}
  • Use the TomTomMapView.getMapAsync((TomTomMap) → Void) method to assign the closure that will be triggered once the map is ready.
    1tomTomMapView.getMapAsync(closure: { (_: TomTomMap) in
    2 /* YOUR CODE GOES HERE */
    3})

Configuring the map

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

1let styleContainer = StyleContainer.defaultStyle
2let amsterdam = CLLocationCoordinate2D(latitude: 52.3764527, longitude: 4.9062047)
3let tenHours = TimeInterval(60 * 60 * 10)
4let resourceCachePolicy = ResourceCachePolicy.cache(tenHours, 200)
5let cameraOptions = CameraOptions(
6 position: amsterdam,
7 zoom: 10.0,
8 tilt: 45,
9 rotation: 0,
10 positionMarkerVerticalOffset: nil
11)
12let mapOptions = MapOptions(
13 mapStyle: styleContainer,
14 mapKey: "YOUR_API_KEY",
15 cameraOptions: cameraOptions,
16 cachePolicy: resourceCachePolicy,
17 styleMode: .dark
18)
19tomTomMapView = TomTomMapView(mapOptions: mapOptions)

MapOptions properties

Propertyrequired/optionalDescription

mapKey

required

Maps API key.

cameraOptions

optional

CameraOptions for a map. Provides position, rotation, tilt, and zoom of the camera. More information can be found in the Camera and animations guide.

cachePolicy

optional

Custom ResourcesCachePolicy used for caching style and tiles. The ResourcesCachePolicy.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 ResourceCachePolicy.noCaching property.

mapStyle

optional

Custom map style provided as StyleContainer. More information about map styling can be found in the Styling the map guide.

styleMode

optional

Provides an initial StyleMode of the map. The default is the TomTom light style. Read more about StyleMode in the Styling the map guide.

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 ResourceCachePolicy 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 ResourceCachePolicy.noCaching value. Otherwise, custom settings can be applied using the ResourceCachePolicy.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.