TomTom SDK for iOS TomTomNavigation

TomTomNavigation

public protocol TomTomNavigation : AnyObject

The TomTomNavigation protocol serves as the primary interface for controlling the navigation process. It provides a comprehensive set of functionalities for managing and customizing a navigation session.

To manage the lifecycle of a navigation session, the protocol offers methods to start() and stop() navigation. It also provides functionality to set and select active routes.

The protocol also includes a range of observers that allow developers to receive updates on various aspects of the navigation.

In addition to the observers, the interface enables customization of the navigation experience. Note that by changing these properties in runtime, the navigation initialization configuration is overridden. Users can configure the betterProposalAcceptanceMode, which determines how to handle better route proposals. Users can also choose the deviationReplanningMode, which defines whether the navigation automatically replans the route. The unitSystem and preferredLanguage can be customized to provide guidance instructions and announcements in the desired format and language.

Important

The current implementation of this API isn’t thread-safe and it’s recommended to make API calls always on the same thread.

  • Adds a NavigationActiveRouteChangeObserver to TomTomNavigation.

    This is notified of changes to the active route whenever a new active route has been set.

    The call is expected on the main queue.

    Declaration

    Swift

    func addActiveRouteChangeObserver(_ observer: NavigationActiveRouteChangeObserver)

    Parameters

    observer

    A class that can handle navigation active route changed events.

  • Adds a NavigationDestinationArrivalObserver to TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addDestinationArrivalObserver(_ observer: NavigationDestinationArrivalObserver)

    Parameters

    observer

    A class that can handle navigation destination arrival events.

  • Adds a NavigationGuidanceObserver to Navigation.

    The call is expected on the main queue.

    Declaration

    Swift

    @available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.\nPlease use TomTomNavigation.addGuidanceUpdateObserver(_:﹚ and TomTomNavigation.addLaneGuidanceUpdateObserver(_:﹚ instead.")
func addGuidanceObserver(_ observer: NavigationGuidanceObserver)

    Parameters

    observer

    A class that can handle navigation guidance events.

  • Adds a GuidanceUpdateObserver that notifies of new TomTomSDKNavigationEngines.Guidance instances.

    This is notified whenever there is a change in location and the TomTomSDKNavigationEngines.GuidanceEngine successfully generates a new TomTomSDKNavigationEngines.Guidance.

    Precondition

    The call is expected on the main queue.

    Declaration

    Swift

    func addGuidanceUpdateObserver(_ observer: GuidanceUpdateObserver)

    Parameters

    observer

    The GuidanceUpdateObserver to be added.

  • Adds a NavigationHorizonObserver to TomTomNavigation.

    The call is expected on the main queue.

    Throws

    HorizonError.observerAlreadyRegistered if this NavigationHorizonObserver object is already added for horizon updates. HorizonError.optionsAlreadyRegistered if these HorizonOptions are already being observed.

    Declaration

    Swift

    func addHorizonObserver(_ observer: NavigationHorizonObserver, options: HorizonOptions) throws

    Parameters

    observer

    A class that can handle navigation horizon events. To add a new observer with the same options, the previous one must be removed first. To add different options with the same observer, the previous one must be removed first.
    options

    The options that define the extent of the paths on the horizon and which map attributes to collect.

  • Adds a LaneGuidanceUpdateObserver to observe and handle new TomTomSDKNavigationEngines.LaneGuidance instances.

    This is notified whenever there is a change in location and the TomTomSDKNavigationEngines.GuidanceEngine successfully generates a new lane guidance.

    Precondition

    The call is expected on the main queue.

    Declaration

    Swift

    func addLaneGuidanceUpdateObserver(_ observer: LaneGuidanceUpdateObserver)

    Parameters

    observer

    The LaneGuidanceUpdateObserver to be added.

  • Adds a NavigationLanguageChangeObserver to TomTomNavigation.

    The call is expected on the main queue. The system keeps a weak reference to the observer.

    Declaration

    Swift

    func addLanguageChangeObserver(_ observer: NavigationLanguageChangeObserver)

    Parameters

    observer

    A class that can handle navigation language change events.

  • Adds a NavigationLocationContextObserver to TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addLocationContextObserver(_ observer: NavigationLocationContextObserver)

    Parameters

    observer

    A class that can handle navigation location context events.

  • Adds a LocationMapMatchingObserver to TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addLocationMapMatchingObserver(_ observer: LocationMapMatchingObserver)

    Parameters

    observer

    A class that can handle navigation map matching events.

  • Adds a NavigationStateChangeObserver to TomTomNavigation. The observer is notified of changes to the navigationState.

    The call is expected on the main queue.

    Declaration

    Swift

    func addNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)

    Parameters

    observer

    A class that can handle navigation state changes.

  • Adds a NavigationProgressObserver to TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addProgressObserver(_ observer: NavigationProgressObserver)

    Parameters

    observer

    A class that can handle navigation start events.

  • Adds a NavigationRouteAddObserver to Navigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addRouteAddObserver(_ observer: NavigationRouteAddObserver)

    Parameters

    observer

    A class that can handle navigation route added events.

  • Adds a NavigationRouteRemoveObserver to Navigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addRouteRemoveObserver(_ observer: NavigationRouteRemoveObserver)

    Parameters

    observer

    A class that can handle navigation route removed events.

  • Adds a NavigationRouteTrackingStateUpdateObserver to TomTomNavigation.

    The call is expected on the main queue. The system keeps a weak reference to the observer.

    Declaration

    Swift

    func addRouteTrackingStateUpdateObserver(_ observer: NavigationRouteTrackingStateUpdateObserver)

    Parameters

    observer

    A class that can handle navigation follow the route events.

  • Adds a NavigationRouteUpdateObserver to TomTomNavigation.

    The call is expected on the main queue. The system keeps a weak reference to the observer.

    Declaration

    Swift

    func addRouteUpdateObserver(_ observer: NavigationRouteUpdateObserver)

    Parameters

    observer

    A class that can handle navigation route updated events.

  • Adds a NavigationWaypointArrivalObserver to TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func addWaypointArrivalObserver(_ observer: NavigationWaypointArrivalObserver)

    Parameters

    observer

    A class that can handle navigation waypoint arrival events.

  • The current BetterProposalAcceptanceMode.

    Declaration

    Swift

    var betterProposalAcceptanceMode: BetterProposalAcceptanceMode { get set }

  • Marks a departure from the given waypoint independently from ArrivalDetectionEngine/hasArrivedAtWaypoint.

    Use this method to manually mark a departure from a waypoint when the arrival detection mechanism is not sufficient; for example, in scenarios such as when the waypoint is a charging station, and the user wishes to trigger immediate replanning after insufficient charging by marking the waypoint as departed, or during delivery operations when the driver must manually confirm departure in cases of route deviations from the planned route.

    The specified waypoint is marked as having been departed from and NavigationWaypointArrivalObserver are notified about this via NavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:).

    Notification via NavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:) completes arrival detection for that particular waypoint. Navigation switches to arrival detection for the next waypoint, if there is one present.

    Prerequisites for this action:

    Throws

    nextWaypointError if calling requirements are not met.

    Declaration

    Swift

    func departFromWaypoint(waypoint: RouteStop) throws

    Parameters

    waypoint

    The TomTomSDKRoute/RouteStop to depart from.

  • Controls how the route deviations are handled.

    When set to TomTomSDKNavigationEngines/DeviationReplanningMode/automatic the navigation replans the route automatically. When set to TomTomSDKNavigationEngines/DeviationReplanningMode/none the navigation does not replan the route.

    The default value is TomTomSDKNavigationEngines/DeviationReplanningMode/automatic.

    Declaration

    Swift

    var deviationReplanningMode: DeviationReplanningMode { get set }

  • A publishable variable that can be used to receive the same events that the delegate presents

    Important

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

    Declaration

    Swift

    var eventPublisher: AnyPublisher<NavigationEvent, Never> { get }

  • The current language used within TomTomNavigation in guidance instructions and announcement language. The initial value is Locale.current. To change language, see preferredLanguage.

    Declaration

    Swift

    var language: Locale { get }

  • The LocationProvider used by the TomTomNavigation for providing location updates to the navigation.

    Declaration

    Swift

    var locationProvider: LocationProvider { get set }

  • Provides a CLLocation for map matching.

    Important

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

    Declaration

    Swift

    var mapMatchedLocationProvider: LocationProvider { get }

  • Provides access to current registered engines and allows updating them.

    Important

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

    Declaration

    Swift

    var navigationEngineRegistry: NavigationEngineRegistry { get set }

  • The current TomTomSDKNavigationEngines/NavigationSnapshot.

    navigationSnapshot is nil at the start of navigation in the following situations:

    • If the location provider is disabled.
    • If the location provider is enabled but unable to find the location.

    Note

    Once navigationSnapshot is defined, it remains defined throughout the navigation session.

    Declaration

    Swift

    var navigationSnapshot: NavigationSnapshot? { get }

  • The current NavigationState within TomTomNavigation.

    The initial value is set to idle.

    To change TomTomNavigation/navigationState, see start(), start(navigationOptions:), stop() and setActiveRoutePlan(_:).

    To observe changes to TomTomNavigation/navigationState see NavigationStateChangeObserver.

    Declaration

    Swift

    var navigationState: NavigationState { get }

  • The preferred language to be used within TomTomNavigation in guidance instructions and announcement language.

    The initial value is Locale.current. If the initial language is not supported, en-US will be used instead. Supported languages can be acquired from GuidanceEngine.availableLanguages.

    Setting the preferred language updates the route. You can check the updated route language using language. If the specified language is not supported, en-US will be used instead.

    To observe language changes, add:

    Declaration

    Swift

    var preferredLanguage: Locale { get set }

  • Removes the NavigationActiveRouteChangeObserver from TomTomNavigation.

    This method allows you to stop receiving updates about active route changes.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeActiveRouteChangeObserver(_ observer: NavigationActiveRouteChangeObserver)

    Parameters

    observer

    A class that can handle navigation active route changed events.

  • Removes the NavigationDestinationArrivalObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeDestinationArrivalObserver(_ observer: NavigationDestinationArrivalObserver)

    Parameters

    observer

    A class that can handle navigation destination arrival events.

  • Removes the NavigationGuidanceObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    @available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.\nPlease use TomTomNavigation.removeGuidanceUpdateObserver(_:﹚ and TomTomNavigation.removeLaneGuidanceUpdateObserver(_:﹚ instead.")
func removeGuidanceObserver(_ observer: NavigationGuidanceObserver)

    Parameters

    observer

    A class that can handle navigation guidance events.

  • Removes a previously added GuidanceUpdateObserver. This method allows you to stop receiving updates about guidance changes.

    Precondition

    The call is expected on the main queue.

    Declaration

    Swift

    func removeGuidanceUpdateObserver(_ observer: GuidanceUpdateObserver)

    Parameters

    observer

    The GuidanceUpdateObserver to be removed.

  • Removes the NavigationHorizonObserver from TomTomNavigation.

    This method should be called on the deinitialization of the observer. The call is expected on the main queue.

    Throws

    HorizonError.observerNotRegistered if NavigationHorizonObserver wasn’t added.

    Declaration

    Swift

    func removeHorizonObserver(_ observer: NavigationHorizonObserver) throws

    Parameters

    observer

    A class that can handle navigation trip events.

  • Removes a previously added LaneGuidanceUpdateObserver.

    This method allows you to stop receiving updates about lane guidance changes.

    Precondition

    The call is expected on the main queue.

    Declaration

    Swift

    func removeLaneGuidanceUpdateObserver(_ observer: LaneGuidanceUpdateObserver)

    Parameters

    observer

    The LaneGuidanceUpdateObserver to be removed.

  • Removes the NavigationLanguageChangeObserver from TomTomNavigation.

    There is no need to remove the observer. If the observer is not removed, the system cleans up when the next event is posted. The call is expected on the main queue. Do not call this method from the deinitializer of the observer, unless you are certain that the observer will be destroyed on the main queue.

    Declaration

    Swift

    func removeLanguageChangeObserver(_ observer: NavigationLanguageChangeObserver)

    Parameters

    observer

    A class that can report on changes to the navigation language.

  • Removes the NavigationLocationContextObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeLocationContextObserver(_ observer: NavigationLocationContextObserver)

    Parameters

    observer

    A class that can handle navigation location context events.

  • Removes the LocationMapMatchingObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeLocationMapMatchingObserver(_ observer: LocationMapMatchingObserver)

    Parameters

    observer

    A class that can handle navigation map matching events.

  • Removes the NavigationStateChangeObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)

    Parameters

    observer

    A class that can handle navigation state changes.

  • Removes the NavigationProgressObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeProgressObserver(_ observer: NavigationProgressObserver)

    Parameters

    observer

    A class that can handle navigation progress events.

  • Removes the NavigationRouteAddObserver from Navigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeRouteAddObserver(_ observer: NavigationRouteAddObserver)

    Parameters

    observer

    A class that can handle navigation route added events.

  • Removes the NavigationRouteRemoveObserver from Navigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeRouteRemoveObserver(_ observer: NavigationRouteRemoveObserver)

    Parameters

    observer

    A class that can handle navigation route removed events.

  • Removes the NavigationRouteTrackingStateUpdateObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeRouteTrackingStateUpdateObserver(_ observer: NavigationRouteTrackingStateUpdateObserver)

    Parameters

    observer

    A class that can handle navigation follow the route events.

  • Removes the NavigationRouteUpdateObserver from TomTomNavigation.

    There is no need to remove the observer. If the observer is not removed, the system cleans up when the next event is posted. The call is expected on the main queue. Do not call this method from the deinitializer of the observer, unless you are certain that the observer will be destroyed on the main queue.

    Declaration

    Swift

    func removeRouteUpdateObserver(_ observer: NavigationRouteUpdateObserver)

    Parameters

    observer

    A class that can handle navigation route updated events.

  • Removes the NavigationWaypointArrivalObserver from TomTomNavigation.

    The call is expected on the main queue.

    Declaration

    Swift

    func removeWaypointArrivalObserver(_ observer: NavigationWaypointArrivalObserver)

    Parameters

    observer

    A class that can handle navigation waypoint arrival events.

  • Selects the Route with provided routeID as active.

    The navigation switches to navigate along the desired route and the following listeners are notified:

    Declaration

    Swift

    func selectActiveRoute(routeId: UUID)

    Parameters

    routeId

    UUID id of route that should be selected.

  • Updates the route plan during ongoing navigation.

    The following listeners are notified:

    • NavigationRouteUpdateObserver/didUpdateRoute(route:options:reason:) with the updated Route, RoutePlanniningOptions and RouteUpdatedReason/manuallyUpdated if current route does not contain the provided routeId, the method does not update the route.
    • didChangeActiveRoute(route:) with the Route if active route has changed.

    • didRemoveRoute(route:reason:) with all other routes except the active Route and manual.

    Throws

    An error if RoutePlan is incompatible with navigation configuration.

    Declaration

    Swift

    func setActiveRoutePlan(_ routePlan: RoutePlan) throws

    Parameters

    routePlan

    The RoutePlan to be set as active. TomTomSDKCommon/Vehicle provided for navigation must be compatible with the given RoutePlan.

  • Starts navigation without specifying a TomTomSDKRoute/Route.

    Use this method to start the navigation in free driving mode.

    Navigation goes through the following steps:

    As a result of successful action, the following observer is notified:

    For examples on how to start navigation, see the developer documentation.

    Throws

    An error if navigation has already started.

    Declaration

    Swift

    func start() throws

  • Starts navigation with the provided NavigationOptions.

    Use this method to start the navigation in active guidance mode with the provided TomTomSDKRoute/Route within the NavigationOptions.

    Navigation goes through the following steps:

    Additionally, the system performs the following operations for the active, i.e., currently navigated TomTomSDKRoute/Route within the NavigationOptions:

    As a result of successful action, the following observer is notified:

    For examples on how to start navigation, see the developer documentation.

    Throws

    An error if navigation has already started or if NavigationOptions are incompatible with navigation configuration.

    Declaration

    Swift

    func start(navigationOptions: NavigationOptions) throws

    Parameters

    navigationOptions

    Details of the navigation options for starting the navigation session. TomTomSDKCommon/Vehicle provided for navigation must be compatible with the given activeRoutePlan.

  • Stops current navigation session and clears data related to it.

    If start has not been called previously, this method has no effect.

    As a result of successful action, the following observer is notified:

    Declaration

    Swift

    func stop()

  • The unit system to be used within TomTomNavigation.

    Once set, it is propagated to other components (e.g. GuidanceEngine) and used for the generation of guidance announcements.

    If the UnitSystemType instance is dynamic then unitSystem is resolved based on the country attribute of the current location:

    • for “USA” and “PRI” it resolves to SpecificUnitSystem/imperialFeet.
    • for “GBR” it resolves to SpecificUnitSystem/imperialYards.
    • for other countries it resolves to SpecificUnitSystem/metric.

    The default value is UnitSystemType.default.

    Declaration

    Swift

    var unitSystem: UnitSystemType { get set }

  • The VehicleProvider used by the TomTomNavigation for providing vehicle updates to the navigation. Information from VehicleProvider.vehicle is leveraged by the TomTomSDKNavigationEngines/HorizonEngine to provide the relevant virtual horizon. Additionally, it is used as a request parameter for route replannings during the navigation session. Notably, it supersedes any vehicle information specified in the TomTomSDKRoutePlanner/RoutePlanningOptions whether at the navigation start, or during any subsequent automatic or manual route replanning events. The VehicleProvider used by the TomTomNavigation for providing vehicle updates to the navigation.

    Declaration

    Swift

    var vehicleProvider: VehicleProvider { get }