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.-
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
VehicleProvider
used by theTomTomNavigation
for providing vehicle updates to the navigation. Information fromVehicleProvider.vehicle
is leveraged by theTomTomSDKNavigationEngines/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 theTomTomSDKRoutePlanner/RoutePlanningOptions
whether at the navigation start, or during any subsequent automatic or manual route replanning events. TheVehicleProvider
used by theTomTomNavigation
for providing vehicle updates to the navigation.Declaration
Swift
var vehicleProvider: VehicleProvider { get }
-
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 }
-
The
LocationProvider
used by theTomTomNavigation
for providing location updates to the navigation.Declaration
Swift
var locationProvider: LocationProvider { get set }
-
Controls how the route deviations are handled.
When set to
TomTomSDKNavigationEngines/DeviationReplanningMode/automatic
the navigation replans the route automatically. When set toTomTomSDKNavigationEngines/DeviationReplanningMode/none
the navigation does not replan the route.The default value is
TomTomSDKNavigationEngines/DeviationReplanningMode/automatic
.Declaration
Swift
var deviationReplanningMode: DeviationReplanningMode { get set }
-
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 thenunitSystem
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 }
- for “USA” and “PRI” it resolves to
-
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 fromGuidanceEngine.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 }
-
The current language used within
TomTomNavigation
in guidance instructions and announcement language. The initial value isLocale.current
. To changelanguage
, seepreferredLanguage
.Declaration
Swift
var language: Locale { get }
-
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
NavigationState
withinTomTomNavigation
.The initial value is set to
idle
.To change
TomTomNavigation/navigationState
, seestart()
,start(navigationOptions:)
,stop()
andsetActiveRoutePlan(_:)
.To observe changes to
TomTomNavigation/navigationState
seeNavigationStateChangeObserver
.Declaration
Swift
var navigationState: NavigationState { get }
-
The current
BetterProposalAcceptanceMode
.Declaration
Swift
var betterProposalAcceptanceMode: BetterProposalAcceptanceMode { get set }
-
The current
TomTomSDKNavigationEngines/NavigationSnapshot
.navigationSnapshot
isnil
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
OncenavigationSnapshot
is defined, it remains defined throughout the navigation session.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var navigationSnapshot: NavigationSnapshot? { get }
-
Starts navigation without specifying a
TomTomSDKRoute/Route
.Use this method to start the navigation in free driving mode.
Navigation goes through the following steps:
- Providing the
TomTomSDKNavigationEngines/MapMatchingResult
viaLocationMapMatchingObserver
. - Providing the updated
TomTomSDKNavigationEngines/LocationContext
viaNavigationLocationContextObserver
. - Providing the updated
TomTomSDKNavigationEngines/HorizonSnapshot
viaNavigationHorizonObserver
.
As a result of successful action, the following observer is notified:
NavigationStateChangeObserver
, with the state set tofreeDriving
.
For examples on how to start navigation, see the developer documentation.
Throws
An error if navigation has already started.Declaration
Swift
func start() throws
- Providing the
-
Starts navigation with the provided
NavigationOptions
.Use this method to start the navigation in active guidance mode with the provided
TomTomSDKRoute/Route
within theNavigationOptions
.Navigation goes through the following steps:
- Providing the
TomTomSDKNavigationEngines/MapMatchingResult
viaLocationMapMatchingObserver
. - Providing the updated
TomTomSDKNavigationEngines/LocationContext
viaNavigationLocationContextObserver
. - Providing the updated
TomTomSDKNavigationEngines/HorizonSnapshot
viaNavigationHorizonObserver
.
Additionally, the system performs the following operations for the active, i.e., currently navigated
TomTomSDKRoute/Route
within theNavigationOptions
:- Calculating
TomTomSDKNavigationEngines/RouteProgress
and updating viaNavigationProgressObserver
. - Checking all followed routes and deviations via
NavigationRouteTrackingStateUpdateObserver
. - Generating
TomTomSDKNavigationEngines/Guidance
viaGuidanceUpdateObserver
. - Detecting arrival, possibly calling
NavigationDestinationArrivalObserver
orNavigationWaypointArrivalObserver
.
As a result of successful action, the following observer is notified:
NavigationStateChangeObserver
, with the state set toactiveGuidance
.NavigationRouteAddObserver
, with theTomTomSDKRoute/Route
andTomTomSDKRoutePlanner/RoutePlanningOptions
set inactiveRoutePlan
, andnavigationStarted
.NavigationActiveRouteChangeObserver
, with theTomTomSDKRoute/Route
set inactiveRoutePlan
.
For examples on how to start navigation, see the developer documentation.
Throws
An error if navigation has already started or ifNavigationOptions
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 givenactiveRoutePlan
. - Providing the
-
Updates the route plan during ongoing navigation.
The following listeners are notified:
NavigationRouteUpdateObserver/didUpdateRoute(route:options:reason:)
with the updatedRoute
,RoutePlanniningOptions
andRouteUpdatedReason/manuallyUpdated
if current route does not contain the providedrouteId
, the method does not update the route.didChangeActiveRoute(route:)
with theRoute
if active route has changed.didRemoveRoute(route:reason:)
with all other routes except the activeRoute
andmanual
.
Throws
An error if
RoutePlan
is incompatible with navigation configuration.Declaration
Swift
func setActiveRoutePlan(_ routePlan: RoutePlan) throws
-
Selects the
Route
with providedrouteID
as active.The navigation switches to navigate along the desired route and the following listeners are notified:
didChangeActiveRoute(route:)
withRoute
selected byrouteID
.didRemoveRoute(route:reason:)
with the previously activeRoute
andmanual
If theRoute
corresponding to the givenrouteId
is not available, changing does not occur.
Declaration
Swift
func selectActiveRoute(routeId: UUID)
Parameters
routeId
UUID
id of route that should be selected. -
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 andNavigationWaypointArrivalObserver
are notified about this viaNavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:)
.Notification via
NavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:)
completes arrival detection for that particularwaypoint
. Navigation switches to arrival detection for the nextwaypoint
, if there is one present.Prerequisites for this action:
- A
didArriveAtWaypoint(waypoint:on:)
notification was previously issued for thiswaypoint
. No
didDepartFromWaypoint(waypoint:on:)
notification was previously issued for thiswaypoint
.
Throws
nextWaypointError
if calling requirements are not met.Declaration
Swift
func departFromWaypoint(waypoint: RouteStop) throws
Parameters
waypoint
The
TomTomSDKRoute/RouteStop
to depart from. - A
-
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:
NavigationStateChangeObserver
, with the state set toidle
.
Declaration
Swift
func stop()
-
Adds a
NavigationStateChangeObserver
toTomTomNavigation
. The observer is notified of changes to thenavigationState
.The call is expected on the main queue.
Declaration
Swift
func addNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)
Parameters
observer
A class that can handle navigation state changes.
-
Removes the
NavigationStateChangeObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)
Parameters
observer
A class that can handle navigation state changes.
-
Adds a
LocationMapMatchingObserver
toTomTomNavigation
.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.
-
Removes the
LocationMapMatchingObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationProgressObserver
toTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func addProgressObserver(_ observer: NavigationProgressObserver)
Parameters
observer
A class that can handle navigation start events.
-
Removes the
NavigationProgressObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeProgressObserver(_ observer: NavigationProgressObserver)
Parameters
observer
A class that can handle navigation progress events.
-
Adds a
NavigationRouteAddObserver
toNavigation
.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.
-
Removes the
NavigationRouteAddObserver
fromNavigation
.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.
-
Adds a
NavigationRouteRemoveObserver
toNavigation
.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.
-
Removes the
NavigationRouteRemoveObserver
fromNavigation
.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.
-
Adds a
NavigationRouteUpdateObserver
toTomTomNavigation
.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.
-
Removes the
NavigationRouteUpdateObserver
fromTomTomNavigation
.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.
-
Adds a
GuidanceUpdateObserver
that notifies of newTomTomSDKNavigationEngines.Guidance
instances.This is notified whenever there is a change in location and the
TomTomSDKNavigationEngines.GuidanceEngine
successfully generates a newTomTomSDKNavigationEngines.Guidance
.Precondition
The call is expected on the main queue.Declaration
Swift
func addGuidanceUpdateObserver(_ observer: GuidanceUpdateObserver)
Parameters
observer
The
GuidanceUpdateObserver
to be added. -
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. -
Adds a
LaneGuidanceUpdateObserver
to observe and handle newTomTomSDKNavigationEngines.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. -
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. -
Adds a
NavigationActiveRouteChangeObserver
toTomTomNavigation
.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.
-
Removes the
NavigationActiveRouteChangeObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationGuidanceObserver
toNavigation
.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.
-
Removes the
NavigationGuidanceObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationLocationContextObserver
toTomTomNavigation
.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.
-
Removes the
NavigationLocationContextObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationDestinationArrivalObserver
toTomTomNavigation
.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.
-
Removes the
NavigationDestinationArrivalObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationWaypointArrivalObserver
toTomTomNavigation
.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.
-
Removes the
NavigationWaypointArrivalObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationHorizonObserver
toTomTomNavigation
.The call is expected on the main queue.
Throws
HorizonError.observerAlreadyRegistered
if thisNavigationHorizonObserver
object is already added for horizon updates.HorizonError.optionsAlreadyRegistered
if theseHorizonOptions
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.
-
Removes the
NavigationHorizonObserver
fromTomTomNavigation
.This method should be called on the deinitialization of the observer. The call is expected on the main queue.
Declaration
Swift
func removeHorizonObserver(_ observer: NavigationHorizonObserver) throws
Parameters
observer
A class that can handle navigation trip events.
-
Adds a
NavigationRouteTrackingStateUpdateObserver
toTomTomNavigation
.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.
-
Removes the
NavigationRouteTrackingStateUpdateObserver
fromTomTomNavigation
.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.
-
Adds a
NavigationLanguageChangeObserver
toTomTomNavigation
.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.
-
Removes the
NavigationLanguageChangeObserver
fromTomTomNavigation
.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.