NavigationServiceDelegate
@objc
public protocol NavigationServiceDelegate
A navigation service delegate interacts with one or more NavigationService
instances (such as MapboxNavigationService
objects) during turn-by-turn navigation. This protocol is the main way that your application can synchronize its state with the SDK’s location-related functionality. Each of the protocol’s methods is optional.
As the user progresses along a route, a navigation service informs its delegate about significant events as they occur, and the delegate has opportunities to influence the route and its presentation. For example, when the navigation service reports that the user has arrived at the destination, your delegate implementation could present information about the destination. It could also customize individual visual or spoken instructions along the route by returning modified instruction objects.
Assign a NavigationServiceDelegate
instance to the NavigationService.delegate
property of the navigation service before you start the service.
The RouterDelegate
protocol defines corresponding methods so that a Router
instance can interact with an object that is both a router delegate and a navigation service, which in turn interacts with a navigation service delegate. Additionally, several location-related methods in this protocol have corresponding methods in the NavigationViewControllerDelegate
protocol, which can be convenient if you are using the navigation service in conjunction with a NavigationViewController
. Normally, you would either implement methods in NavigationServiceDelegate
or NavigationViewControllerDelegate
but not RouterDelegate
.
Seealso
NavigationViewControllerDelegateSeealso
RouterDelegate-
Returns whether the navigation service should be allowed to calculate a new route.
If implemented, this method is called as soon as the navigation service detects that the user is off the predetermined route. Implement this method to conditionally prevent rerouting. If this method returns
true
,navigationService(_:willRerouteFrom:)
will be called immediately afterwards.Declaration
Swift
@objc(navigationService:shouldRerouteFromLocation:) optional func navigationService(_ service: NavigationService, shouldRerouteFrom location: CLLocation) -> Bool
Parameters
service
The navigation service that has detected the need to calculate a new route.
location
The user’s current location.
Return Value
True to allow the navigation service to calculate a new route; false to keep tracking the current route.
-
Called immediately before the navigation service calculates a new route.
This method is called after
navigationService(_:shouldRerouteFrom:)
is called, simultaneously with theNavigationServiceWillReroute
notification being posted, and beforenavigationService(_:didRerouteAlong:)
is called.Declaration
Swift
@objc(navigationService:willRerouteFromLocation:) optional func navigationService(_ service: NavigationService, willRerouteFrom location: CLLocation)
Parameters
service
The navigation service that will calculate a new route.
location
The user’s current location.
-
Called when a location has been identified as unqualified to navigate on.
See
CLLocation.isQualified
for more information about what qualifies a location.- return: If
true
, the location is discarded and theNavigationService
will not consider it. Iffalse
, the location will not be thrown out.
Declaration
Swift
@objc(navigationService:shouldDiscardLocation:) optional func navigationService(_ service: NavigationService, shouldDiscard location: CLLocation) -> Bool
Parameters
service
The navigation service that discarded the location.
location
The location that will be discarded.
- return: If
-
Called immediately after the navigation service receives a new route.
This method is called after
navigationService(_:willRerouteFrom:)
and simultaneously with theNavigationServiceDidReroute
notification being posted.Declaration
Swift
@objc(navigationService:didRerouteAlongRoute:at:proactive:) optional func navigationService(_ service: NavigationService, didRerouteAlong route: Route, at location: CLLocation?, proactive: Bool)
Parameters
service
The navigation service that has calculated a new route.
route
The new route.
-
Called when the navigation service fails to receive a new route.
This method is called after
navigationService(_:willRerouteFrom:)
and simultaneously with theNavigationServiceDidFailToReroute
notification being posted.Declaration
Swift
@objc(navigationService:didFailToRerouteWithError:) optional func navigationService(_ service: NavigationService, didFailToRerouteWith error: Error)
Parameters
service
The navigation service that has calculated a new route.
error
An error raised during the process of obtaining a new route.
-
Called when the navigation service updates the route progress model.
Declaration
Swift
@objc(navigationService:didUpdateProgress:withLocation:rawLocation:) optional func navigationService(_ service: NavigationService, didUpdate progress: RouteProgress, with location: CLLocation, rawLocation: CLLocation)
Parameters
service
The navigation service that received the new locations.
progress
the RouteProgress model that was updated.
location
the guaranteed location, possibly snapped, associated with the progress update.
rawLocation
the raw location, from the location manager, associated with the progress update.
-
Called when the navigation service detects that the user has passed a point at which an instruction should be displayed.
Declaration
Swift
@objc(navigationService:didPassVisualInstructionPoint:routeProgress:) optional func navigationService(_ service: NavigationService, didPassVisualInstructionPoint instruction: VisualInstructionBanner, routeProgress: RouteProgress)
Parameters
service
The navigation service that passed the instruction point.
instruction
The instruction to be presented.
routeProgress
The route progress object that the navigation service is updating.
-
Called when the navigation service detects that the user has passed a point at which an instruction should be spoken.
Declaration
Swift
@objc(navigationService:didPassSpokenInstructionPoint:routeProgress:) optional func navigationService(_ service: NavigationService, didPassSpokenInstructionPoint instruction: SpokenInstruction, routeProgress: RouteProgress)
Parameters
service
The navigation service that passed the instruction point.
instruction
The instruction to be spoken.
routeProgress
The route progress object that the navigation service is updating.
-
Called as the navigation service approaches a waypoint.
This message is sent, once per progress update, as the user is approaching a waypoint. You can use this to cue UI, to do network pre-loading, etc.
Important
This method will likely be called several times as you approach a destination. If only one consumption of this method is desired, then usage of an internal flag is recommended.Declaration
Swift
@objc(navigationService:willArriveAtWaypoint:after:distance:) optional func navigationService(_ service: NavigationService, willArriveAt waypoint: Waypoint, after remainingTimeInterval: TimeInterval, distance: CLLocationDistance)
Parameters
service
The Navigation service that is detecting the destination approach.
waypoint
The waypoint that the service is arriving at.
remainingTimeInterval
The estimated number of seconds until arrival.
distance
The current distance from the waypoint, in meters.
-
Called when the navigation service arrives at a waypoint.
You can implement this method to prevent the navigation service from automatically advancing to the next leg. For example, you can and show an interstitial sheet upon arrival and pause navigation by returning
false
, then continue the route when the user dismisses the sheet. If this method is unimplemented, the navigation service automatically advances to the next leg when arriving at a waypoint.Postcondition
If you return false, you must manually advance to the next leg: obtain the value of therouteProgress
property, then increment theRouteProgress.legIndex
property.Declaration
Swift
@objc(navigationService:didArriveAtWaypoint:) optional func navigationService(_ service: NavigationService, didArriveAt waypoint: Waypoint) -> Bool
Parameters
service
The navigation service that has arrived at a waypoint.
waypoint
The waypoint that the controller has arrived at.
Return Value
True to advance to the next leg, if any, or false to remain on the completed leg.
-
Called when the navigation service arrives at a waypoint.
You can implement this method to allow the navigation service to continue check and reroute the user if needed. By default, the user will not be rerouted when arriving at a waypoint.
Declaration
Swift
@objc(navigationService:shouldPreventReroutesWhenArrivingAtWaypoint:) optional func navigationService(_ service: NavigationService, shouldPreventReroutesWhenArrivingAt waypoint: Waypoint) -> Bool
Parameters
service
The navigation service that has arrived at a waypoint.
waypoint
The waypoint that the controller has arrived at.
Return Value
True to prevent the navigation service from checking if the user should be rerouted.
-
Called when the navigation service will disable battery monitoring.
Implementing this method will allow developers to change whether battery monitoring is disabled when
NavigationService
is deinited.Declaration
Swift
@objc(navigationServiceShouldDisableBatteryMonitoring:) optional func navigationServiceShouldDisableBatteryMonitoring(_ service: NavigationService) -> Bool
Parameters
service
The navigation service that will change the state of battery monitoring.
Return Value
A bool indicating whether to disable battery monitoring when the RouteController is deinited.
-
Called when the navigation service is about to begin location simulation.
Implementing this method will allow developers to react when
poor GPS
location-simulation is about to start, possibly to show aPoor GPS
banner in the UI.Declaration
Swift
@objc optional func navigationService(_ service: NavigationService, willBeginSimulating progress: RouteProgress, becauseOf reason: SimulationIntent)
Parameters
service
The navigation service that will simulate the routes’ progress.
progress
the current RouteProgress model.
reason
The reason the simulation will be initiated. Either manual or poorGPS.
-
Called after the navigation service begins location simulation.
Implementing this method will allow developers to react when
poor GPS
location-simulation has started, possibly to show aPoor GPS
banner in the UI.Declaration
Swift
@objc optional func navigationService(_ service: NavigationService, didBeginSimulating progress: RouteProgress, becauseOf reason: SimulationIntent)
Parameters
service
The navigation service that is simulating the routes’ progress.
progress
the current RouteProgress model.
reason
The reason the simulation has been initiated. Either manual or poorGPS.
-
Called when the navigation service is about to end location simulation.
Implementing this method will allow developers to react when
poor GPS
location-simulation is about to end, possibly to hide aPoor GPS
banner in the UI.Declaration
Swift
@objc optional func navigationService(_ service: NavigationService, willEndSimulating progress: RouteProgress, becauseOf reason: SimulationIntent)
Parameters
service
The navigation service that is simulating the routes’ progress.
progress
the current RouteProgress model.
reason
The reason the simulation was initiated. Either manual or poorGPS.
-
Called after the navigation service ends location simulation.
Implementing this method will allow developers to react when
poor GPS
location-simulation has ended, possibly to hide aPoor GPS
banner in the UI.Declaration
Swift
@objc optional func navigationService(_ service: NavigationService, didEndSimulating progress: RouteProgress, becauseOf reason: SimulationIntent)
Parameters
service
The navigation service that was simulating the routes’ progress.
progress
the current RouteProgress model.
reason
The reason the simulation was initiated. Either manual or poorGPS.