User location

VERSION 0.2.1455
PUBLIC PREVIEW

The TomTom Map SDK allows you to show the current user location on the map. The location data is provided by the LocationEngine. The default implementation (DefaultCLLocationEngine) is provided by TomTom. CLLocationManager is used to obtain the user location. Learn more about existing location engines in the Built-in location engines.

To make it work you have to configure the following Purpose Strings in the Xcode build setting or in Info.plist: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, or NSLocationAlwaysUsageDescription. The correct key must be included or authorization requests will immediately fail and the map will not be able to get the user location.

To display the current location button, please make sure to add the following line of code inside the onMapReady method. It is required to get the location.

1func tomTomMapView(_ mapView: TomTomMapView, onMapReady map: TomTomMap) {
2 mapView.currentLocationButtonVisibilityPolicy = .hiddenWhenCentered
3}

When the above steps are done, you should be able to display the current location. When the recenter button is pressed, the camera will move to the user’s current location.

Using the location engine with the map

Location updates are generated by the LocationEngine. DefaultCLLocationEngine is used to generate location updates. If you want to want to use a different location source or implement it according to your needs, your location engine needs to conform to LocationEngine. Here is an empty implementation that can be used as a template:

1class UserLocationEngine: LocationEngine {
2 // It should be set to last known location.
3 var location: GeoLocation?
4
5 func start() {
6 // Here you should start location engine.
7 // Might be called from private queue.
8 }
9
10 func stop() {
11 // Here you should stop location engine.
12 // After calling this method your location engine
13 // should not provide any location updates.
14 // Might be called from private queue.
15 }
16
17 func addObserver(_: LocationEngineObserver) {
18 // Your location engine should support observer pattern.
19 // Implementation should support multiple observers added at time.
20 // Methods from `LocationEngineObserver` should be called
21 // each time new location data is available.
22 }
23
24 func removeObserver(_: LocationEngineObserver) {
25 // This method should remove observer from observers list.
26 }
27}

Then it can be set and the map will start using it:

1let customEngine = UserLocationEngine()
2tomTomMap.setCustomLocationEngine(customEngine)
3tomTomMap.activateLocationEngine()

It will be used by the map to position the location marker according to the position updates.

You can also use the TomTomMap object to retrieve the currently used LocationEngine, and access the latest user location:

let lastLocation = tomTomMap.locationEngine.location

The first time the map is launched you will be asked to allow the map to use your location. If you agreed, the user location will be shown as a navigation chevron on the map.


LocationIndicatorType

This parameter specifies the type of the marker.

The Map SDK provides two default markers with the ability to add a custom marker:

  • userLocation - shows the user location pin.
  • navigationChevron - shows the navigation chevron.
  • none - completely hides the location marker.
  • custom - gives the ability to add a custom .glb model as a location indicator.

To resize the location indicator, add a custom scale to userLocation and navigationChevron.

tomTomMap.locationIndicatorType = .userLocation(scale: 2.5)
tomTomMap.locationIndicatorType = .navigationChevron(scale: 2.5)

To switch from the default, set the appropriate value of TomTomMapView.locationIndicatorType.

1tomTomMap.locationIndicatorType = .userLocation
2tomTomMap.locationIndicatorType = .navigationChevron
3tomTomMap.locationIndicatorType = .none
4tomTomMap.locationIndicatorType = .custom(
5 modelPath: "asset://CUSTOM_MODEL.glb",
6 sizes: [PositionMarkerSize(zoomLevel: 2, size: 200)]
7)

To add a custom location marker, specify a model path for the .glb file, and specify a size. To add the file.glb file to your project path for the model, it should look like asset://file.glb. To set a size for a custom location marker, provide an array of PositionMarkerSize to specify the model’s size on the different zoom levels.

1tomTomMap.locationIndicatorType = .custom(
2 modelPath: "asset://car.glb",
3 sizes: [
4 PositionMarkerSize(zoomLevel: 2, size: 150),
5 PositionMarkerSize(zoomLevel: 10, size: 200),
6 ]
7)

Location marker click detection

The Map SDK provides a delegate method that can be used to receive onclick events performed on the location marker. If the user taps on the marker, the method from TomTomMapDelegate will be executed.

1extension UserLocationViewController: TomTomMapDelegate {
2 func tomTomMap(_: TomTomMap, didTapOnCurrentLocation _: CLLocationCoordinate2D) {}
3}
4
5// MARK: TomTomMapViewDelegate

It provides the coordinate of the location on the map.