User location

VERSION 0.2.2822
PUBLIC PREVIEW

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

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 mapView(_ mapView: MapView, 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 provider with the map

Location updates are generated by the LocationProvider. DefaultCLLocationProvider 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 provider needs to conform to LocationProvider. Here is an empty implementation that can be used as a template:

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

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

1let customProvider = UserLocationProvider()
2map.locationProvider = customProvider
3map.activateLocationProvider()

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 LocationProvider, and access the latest user location:

let lastLocation = map.locationProvider.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.


LocationIndicator

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.

The location indicator is a navigationChevron by default. After the user authorizes the app to use their location, the chevron is displayed on the map.

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

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

To switch from the default, set the appropriate value of MapView.LocationIndicator.

1map.locationIndicatorType = .userLocation
2map.locationIndicatorType = .navigationChevron
3map.locationIndicatorType = .none
4map.locationIndicatorType = .custom(modelPath: "asset://CUSTOM_MODEL.glb", scale: 10)

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.

map.locationIndicatorType = .custom(modelPath: "asset://car.glb", scale: 10)

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 MapDelegate will be executed.

1extension UserLocationViewController: MapDelegate {
2 func map(_: TomTomMap, didTapOnCurrentLocation _: CLLocationCoordinate2D) {}
3}
4
5// MARK: MapViewDelegate

It provides the coordinate of the location on the map.