NavigationVisualizationServiceProtocol

public protocol NavigationVisualizationServiceProtocol : AnyObject

Entry point for all methods related to the navigation visualization addon.

To start using the Navigation Visualization addon, 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.selectRoute(_:) to select a route on which to navigate. You can access the collection of route primitives displayed on the map using routes property. The selected 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 life cycle, 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 collection of TomTomSDKMapDisplay.Route that is being displayed on the map.

    During display of a TomTomSDKMapDisplay.Route, this list contains the selected route and the alternative routes. The alternative routes are removed from this list when a navigation session starts, so that it only contains the selectedRoute (AKA the active route). This list will be empty after calling clear().

    Declaration

    Swift

    var routes: [TomTomSDKMapDisplay.Route] { get }

  • The TomTomSDKMapDisplay.Route selected for navigation.

    This is nil before routes has been displayed with displayRoutes(routes:), or after calling clear(). During a navigation session, this property contains the active route.

    Declaration

    Swift

    var selectedRoute: TomTomSDKMapDisplay.Route? { get }

  • Gets the collection of Line that are being displayed on a certain TomTomSDKRoute.Route as traffic incident.

    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 }

  • Displays collection of TomTomSDKRoute.Route on the map.

    Adds TomTomSDKRoute.Route instances to the map contained in the collections. By default, the first route of the plan is selected, but you can select a different route using selectRoute(route:). Consecutive calls of this method replace the previous TomTomSDKRoute.Routecollection being displayed. If the provided TomTomSDKRoute.Route collection contains an empty list of routes, then this method does nothing.

    Declaration

    Swift

    func displayRoutes(routes: [TomTomSDKRoute.Route])

    Parameters

    routes

    Routes to be displayed.

  • Selects a 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 selectRoute(_ route: TomTomSDKMapDisplay.Route)

    Parameters

    route

    Route to be highlighted

  • Clears instance data of NavigationVisualizationServiceProtocol. Removes all routes that have been added with displayRoutes(routes:) from the map, and sets selectedRoute 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.

  • The traffic incidents on route visibility

    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 will be 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 will be automatically hidden while using navigation. This is particularly useful for improving the user’s focus during navigation.

    Declaration

    Swift

    func hideTrafficIncidents()

  • Designated initialiser.

    Declaration

    Swift

    init(
    map: TomTomMap,
    navigation: Navigation,
    styleConfiguration: StyleConfiguration
)

    Parameters

    map

    TomTomMap to be injected
    navigation

    The entry point for interacting with and customizing navigation.
    styleConfiguration

    The style configuration for the elements of the navigation visualization.