NavigationVisualizationServiceProtocol

public protocol NavigationVisualizationServiceProtocol : AnyObject

Entry point for all methods related to the navigation visualization.

To start using the navigation visualization, create an instance using NavigationVisualizationServiceBuilder.build(map:navigation:styleConfiguration:). Then provide the instance with a collection of TomTomSDKRoute.Route using the NavigationVisualizationServiceProtocol.displayRoutes(routes:) method. After that, the TomTomSDKRoute.Route contained in the collection is displayed on the map, and you can use NavigationVisualizationServiceProtocol.setActiveRoute(_:) to select a route on which to navigate. You can access the collection of route primitives displayed on the map using routes property. The active route and the alternative routes are styled with the properties contained in the StyleConfiguration provided to NavigationVisualizationServiceBuilder.build(map:navigation:styleConfiguration:). Next, select the type of navigation guidance with NavigationVisualizationServiceProtocol.selectGuidanceType(_:), and start the navigation session with Navigation.start(). Once the navigation session is started, the route that is selected becomes the active route. When you’re done using a NavigationVisualizationServiceProtocol instance, call Navigation.stop(). Then call NavigationVisualizationServiceProtocol.clear() to remove all the primitives that have been added to the map by the add-on.

If a TomTomSDKRoute.Route has traffic data available, traffic incidents are displayed on the map on top of the TomTomSDKRoute.Route. You can access the list of traffic incident lines that are on a route using NavigationVisualizationServiceProtocol.trafficOnRoutes property by UUID of corresponding TomTomSDKMapDisplay.Route.

The navigation visualization add-on observes certain events during its lifecycle so that it can react automatically to important events:

  • NavigationArrivalObserver.didStart(with:): The add-on observes when a navigation session starts.
  • NavigationRouteObserver.didReplanRoute(replannedRoute:reason:) : The add-on observes when the current route is updated.
  • NavigationProgressObserver.didUpdateProgress(progress:): The add-on observes when progress is updated on the current route.

  • NavigationArrivalObserver.didArriveAtDestinationOn(route:): The add-on observes when the driver reaches the destination.

Important

This is a Public Preview API. It may be changed or removed at any time.

  • The list of routes displayed on the map contains the: - active route - alternative routes.

    The active route is available after calling the setActiveRoute(_:) method. When a navigation session starts, the alternative routes are removed from this list. The list contains only the active route (activeRoute). After calling clear(), the list is empty.

    Declaration

    Swift

    var routes: [TomTomSDKMapDisplay.Route] { get }

  • The TomTomSDKMapDisplay.Route selected for navigation. This property contains the active route during a navigation session. This is nil (empty) before routes have been displayed with displayRoutes(routes:), or after calling clear().

    Declaration

    Swift

    var activeRoute: TomTomSDKMapDisplay.Route? { get }

  • Retrieves the list of traffic incidents as line objects.

    Declaration

    Swift

    var trafficOnRoutes: [UUID : [TrafficIncident]] { get }

  • Enables or disables automatic zoom to routes when displayRoutes(routes:_) is invoked.

    The default is true.

    Declaration

    Swift

    var zoomToRoutesEnabled: Bool { get set }

  • Display a list of routes on the map. By default, the first route in the list is set as active. You can select a different route using setActiveRoute.

    Declaration

    Swift

    func displayRoutes(routes: [TomTomSDKRoute.Route])

    Parameters

    routes

    Routes to be displayed.

  • Set an active TomTomSDKMapDisplay.Route to be navigated, when a navigation session starts.

    If the provided TomTomSDKMapDisplay.Route is not a route displayed with displayRoutes(routes:), then this method does nothing.

    Declaration

    Swift

    func setActiveRoute(_ route: TomTomSDKMapDisplay.Route)

    Parameters

    route

    Route to be highlighted.

  • Removes all routes that have been added with displayRoutes(routes:) from the map, and sets activeRoute to nil.

    Declaration

    Swift

    func clear()

  • The type of navigation guidance selected.

    The default is GuidanceType.regular. You can call selectGuidanceType(:_) to select a different navigation guidance type.

    Declaration

    Swift

    var guidanceType: GuidanceType { get }

  • Selects the type of guidance to be used when a navigation session starts.

    When the type GuidanceType.regular is selected, the add-on presents regular navigation guidance. When the type GuidanceType.laneLevel is selected, the add-on is instructed to present lane-level guidance, but it may still present regular navigation guidance. This happens because of an internal fallback mechanism that switches from lane-level guidance mode to the regular one when no lane-level data is available. The add-on switches back to lane-level guidance mode as soon as lane-level data is available again. Note that the property guidanceType is not affected when this fallback mechanism kicks in.

    Important: DO NOT USE GuidanceType.lanelevel. THIS FEATURE IS NOT IMPLEMENTED YET.

    Declaration

    Swift

    func selectGuidanceType(_ guidanceType: GuidanceType)

    Parameters

    guidanceType

    The GuidanceType to be used during the navigation session.

  • Toggle the visibility of traffic incidents on route.

    The default is true.

    Declaration

    Swift

    var trafficIncidentsEnabled: Bool { get set }

  • Shows traffic incidents on the map, highlighting areas where there are traffic jams and reported road incidents or accidents.

    Important

    This method should be preferred over the direct call to TomTomMap.showTrafficIncidents() for compatibility and consistency. By using this method, any non-relevant incidents are automatically hidden while using navigation. This is particularly useful for improving the user’s focus during navigation.

    Declaration

    Swift

    func showTrafficIncidents()

  • Hides traffic incidents on the map, removing any markers or highlights related to traffic incidents.

    Important

    This method should be preferred over the direct call to TomTomMap.hideTrafficIncidents() for compatibility and consistency. By using this method, any non-relevant incidents are automatically hidden while using navigation. This is particularly useful for improving the user’s focus during navigation.

    Declaration

    Swift

    func hideTrafficIncidents()

  • Object to address visualization of vehicle-horizon such as configuration, user interaction, etc.

    Declaration

    Swift

    var horizonVisualization: HorizonVisualization { get }