NavigationViewControllerDelegate
public protocol NavigationViewControllerDelegate : VisualInstructionDelegate
The NavigationViewControllerDelegate
protocol provides methods for configuring the map view shown by a NavigationViewController
and responding to the cancellation of a navigation session.
For convenience, several location-related methods in the NavigationServiceDelegate
protocol have corresponding methods in this protocol.
-
navigationViewControllerDidDismiss(_:byCanceling:)
Default implementationCalled when the navigation view controller is dismissed, such as when the user ends a trip.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewControllerDidDismiss(_ navigationViewController: NavigationViewController, byCanceling canceled: Bool)
Parameters
navigationViewController
The navigation view controller that was dismissed.
canceled
True if the user dismissed the navigation view controller by tapping the Cancel button; false if the navigation view controller dismissed by some other means.
-
navigationViewController(_:didUpdate:with:rawLocation:)
Default implementationCalled when movement of the user updates the route progress model.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didUpdate progress: RouteProgress, with location: CLLocation, rawLocation: CLLocation)
Parameters
navigationViewController
The ViewController 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.
-
navigationViewController(_:didAdd:pointAnnotationManager:)
Default implementationTells the receiver that the final destination
PointAnnotation
was added to theNavigationViewController
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didAdd finalDestinationAnnotation: PointAnnotation, pointAnnotationManager: PointAnnotationManager)
Parameters
navigationViewController
The
NavigationViewController
object.finalDestinationAnnotation
The point annotation that was added to the map view.
pointAnnotationManager
The object that manages the point annotation in the map view.
-
navigationViewController(_:willArriveAt:after:distance:)
Default implementationCalled as the user 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.
Note
This method will likely be called several times as you approach a destination. To respond to the user’s arrival only once, your delegate can define a property that keeps track of whether this method has already been called for the given waypoint.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, willArriveAt waypoint: Waypoint, after remainingTimeInterval: TimeInterval, distance: CLLocationDistance)
Parameters
navigationViewController
The Navigation VC that is detecting the users’ 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.
-
navigationViewController(_:didArriveAt:)
Default implementationCalled when the user arrives at the destination waypoint for a route leg.
This method is called when the navigation view controller arrives at the waypoint. You can implement this method to prevent the navigation view controller 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 view controller automatically advances to the next leg when arriving at a waypoint.Postcondition
If you returnfalse
within this method, you must manually advance to the next leg using theRouter.advanceLegIndex(completionHandler:)
method. ObtainRouter
via theNavigationViewController.navigationService
andNavigationService.router
properties.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didArriveAt waypoint: Waypoint) -> Bool
Parameters
navigationViewController
The navigation view controller that has arrived at a waypoint.
waypoint
The waypoint that the user has arrived at.
Return Value
True to automatically advance to the next leg, or false to remain on the now completed leg.
-
navigationViewController(_:didSelect:)
Default implementationTells the receiver that a waypoint was selected.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didSelect waypoint: Waypoint)
Parameters
navigationViewController
The
NavigationViewController
object.waypoint
The waypoint that was selected.
-
navigationViewController(_:shouldRerouteFrom:)
Default implementationReturns whether the navigation view controller should be allowed to calculate a new route.
If implemented, this method is called as soon as the navigation view controller detects that the user is off the predetermined route. Implement this method to conditionally prevent rerouting. If this method returns
true
,navigationViewController(_:willRerouteFrom:)
will be called immediately afterwards.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, shouldRerouteFrom location: CLLocation) -> Bool
Parameters
navigationViewController
The navigation view controller that has detected the need to calculate a new route.
location
The user’s current location.
Return Value
True to allow the navigation view controller to calculate a new route; false to keep tracking the current route.
-
navigationViewController(_:shouldProactivelyRerouteFrom:to:completion:)
Default implementationAsks permission to proceed with found proactive reroute and apply it as main route.
If implemented, this method is called as soon as the navigation view controller detects route faster than the current one. This only happens if
Router.reroutesProactively
is set totrue
(default). Calling providedcompletion
results in new route to be set, without triggering usual rerouting delegate methods.Default Implementation
Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, shouldProactivelyRerouteFrom location: CLLocation, to route: Route, completion: @escaping () -> Void)
Parameters
navigationViewController
The navigation view controller that has detected faster new route
location
The user’s current location.
route
The route found.
completion
Completion to be called to allow the navigation view controller to apply a new route; Ignoring calling the completion will ignore the faster route aswell.
-
navigationViewController(_:shouldPreventReroutesWhenArrivingAt:)
Default implementationCalled when the user arrives at a waypoint.
Return false to continue checking if reroute is needed. By default, the user will not be rerouted when arriving at a waypoint.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, shouldPreventReroutesWhenArrivingAt waypoint: Waypoint) -> Bool
Parameters
navigationViewController
The navigation view controller that has detected the need to calculate a new route.
waypoint
The waypoint that the controller has arrived at.
Return Value
True to prevent reroutes.
-
navigationViewController(_:willRerouteFrom:)
Default implementationCalled immediately before the navigation view controller calculates a new route.
This method also allows customizing the rerouting by providing custom
RouteResponse
. SDK will then treat it as if it was fetched as usual and apply as a reroute.Note
Multiple method calls will not interrupt the first ongoing request.This method is called after
navigationViewController(_:shouldRerouteFrom:)
is called, simultaneously with theNotification.Name.routeControllerWillReroute
notification being posted, and beforenavigationViewController(_:modifiedOptionsForReroute:)
is called.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, willRerouteFrom location: CLLocation?)
Parameters
navigationViewController
The navigation view controller that will calculate a new route.
location
The user’s current location.
-
navigationViewController(_:modifiedOptionsForReroute:)
Default implementationWhen reroute is happening, navigation view controller suggests to customize the
RouteOptions
used to calculate new route.This method is called after
navigationViewController(_:willRerouteFrom:)
is called, and beforenavigationViewController(_:didRerouteAlong:)
is called. This method is not called on proactive rerouting.Default implementation does no modifications.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, modifiedOptionsForReroute options: RouteOptions) -> RouteOptions
Parameters
navigationViewController
The navigation view controller that will calculate a new route.
options
Original
RouteOptions
.Return Value
Modified
RouteOptions
. -
navigationViewController(_:didRerouteAlong:)
Default implementationCalled immediately after the navigation view controller receives a new route.
This method is called after
navigationViewController(_:modifiedOptionsForReroute:)
and simultaneously with theNotification.Name.routeControllerDidReroute
notification being posted.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didRerouteAlong route: Route)
Parameters
navigationViewController
The navigation view controller that has calculated a new route.
route
The new route.
-
navigationViewController(_:didUpdateAlternatives:removedAlternatives:)
Default implementationCalled when navigation view controller has detected a change in alternative routes list.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didUpdateAlternatives updatedAlternatives: [AlternativeRoute], removedAlternatives: [AlternativeRoute])
Parameters
navigationViewController
The navigation view controller reporting an update.
updatedAlternatives
Array of actual alternative routes.
removedAlternatives
Array of alternative routes which are no longer actual.
-
navigationViewController(_:didFailToUpdateAlternatives:)
Default implementationCalled when navigation view controller has failed to change alternative routes list.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didFailToUpdateAlternatives error: AlternativeRouteError)
Parameters
navigationViewController
The navigation view controller reporting an update.
error
An error occured.
-
navigationViewController(_:didSwitchToCoincidentOnlineRoute:)
Default implementationCalled when navigation view controller has automatically switched to the coincide online route.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didSwitchToCoincidentOnlineRoute coincideRoute: Route)
Parameters
navigationViewController
The navigation view controller reporting an update.
coincideRoute
A route taken.
-
navigationViewController(_:willTakeAlternativeRoute:at:)
Default implementationCalled when navigation view controller has detected user taking an alternative route.
This method is called before updating main route.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, willTakeAlternativeRoute route: Route, at location: CLLocation?)
Parameters
navigationViewController
The navigation view controller that has detected turning to the alternative.
route
The alternative route which will be taken as new main.
location
The user’s current location.
-
navigationViewController(_:didTakeAlternativeRouteAt:)
Default implementationCalled when navigation view controller has finished switching to an alternative route
This method is called after
navigationViewController(_:willTakeAlternativeRoute:)
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didTakeAlternativeRouteAt location: CLLocation?)
Parameters
navigationViewController
The navigation view controller that switched to the alternative.
location
The user’s current location.
-
navigationViewController(_:didFailToTakeAlternativeRouteAt:)
Default implementationCalled when navigation view controller has failed to take an alternative route.
This method is called after
navigationViewController(_:willTakeAlternativeRoute:)
.This call would indicate that something went wrong during setting new main route.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didFailToTakeAlternativeRouteAt location: CLLocation?)
Parameters
navigationViewController
The navigation view controller which tried to switch to the alternative.
location
The user’s current location.
-
Tells the receiver that the user has selected a continuous alternative route by interacting with the map view.
Continuous alternatives are all non-primary routes, reported during the navigation session.
Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didSelect continuousAlternative: AlternativeRoute)
Parameters
navigationViewController
The
NavigationViewController
object.continuousAlternative
The route that was selected.
-
navigationViewController(_:didFailToRerouteWith:)
Default implementationCalled when the navigation view controller fails to receive a new route.
This method is called after
navigationViewController(_:modifiedOptionsForReroute:)
and simultaneously with theNotification.Name.routeControllerDidFailToReroute
notification being posted.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didFailToRerouteWith error: Error)
Parameters
navigationViewController
The navigation view controller that has calculated a new route.
error
An error raised during the process of obtaining a new route.
-
navigationViewController(_:didRefresh:)
Default implementationCalled immediately after the navigation view controller refreshes the route.
This method is called simultaneously with the
Notification.Name.routeControllerDidRefreshRoute
notification being posted.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didRefresh routeProgress: RouteProgress)
Parameters
navigationViewController
The navigation view controller that has refreshed the route.
routeProgress
The updated route progress with the refreshed route.
-
navigationViewController(_:routeLineLayerWithIdentifier:sourceIdentifier:)
Default implementationReturns an
LineLayer
that determines the appearance of the route line.If this method is not implemented, the navigation view controller’s map view draws the route line using default
LineLayer
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, routeLineLayerWithIdentifier identifier: String, sourceIdentifier: String) -> LineLayer?
Parameters
navigationViewController
The
NavigationViewController
object, on surface of which route line is drawn.identifier
The
LineLayer
identifier.sourceIdentifier
Identifier of the source, which contains the route data that this method would style.
Return Value
A
LineLayer
that is applied to the route line. -
navigationViewController(_:routeCasingLineLayerWithIdentifier:sourceIdentifier:)
Default implementationReturns an
LineLayer
that determines the appearance of the casing around the route line.If this method is not implemented, the navigation view controller’s map view draws the casing for the route line using default
LineLayer
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, routeCasingLineLayerWithIdentifier identifier: String, sourceIdentifier: String) -> LineLayer?
Parameters
navigationViewController
The
NavigationViewController
object, on surface of which route line is drawn.identifier
The
LineLayer
identifier.sourceIdentifier
Identifier of the source, which contains the route data that this method would style.
Return Value
A
LineLayer
that is applied as a casing around the route line. -
navigationViewController(_:routeRestrictedAreasLineLayerWithIdentifier:sourceIdentifier:)
Default implementationReturns an
LineLayer
that determines the appearance of the restricted areas portions of the route line.If this method is not implemented, the navigation view controller’s map view draws the areas using default
LineLayer
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, routeRestrictedAreasLineLayerWithIdentifier identifier: String, sourceIdentifier: String) -> LineLayer?
Parameters
navigationViewController
The
NavigationViewController
object, on surface of which route line is drawn.identifier
The
LineLayer
identifier.sourceIdentifier
Identifier of the source, which contains the route data that this method would style.
Return Value
A
LineLayer
that is applied as restricted areas on the route line. -
navigationViewController(_:willAdd:)
Default implementationAsks the receiver to adjust the default layer which will be added to the map view and return a
Layer
.If this method is not implemented, the navigation view controller’s map view draws the default
layer
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, willAdd layer: Layer) -> Layer?
Parameters
navigationViewController
The
NavigationViewController
object, on surface of which route line is drawn.layer
A default
Layer
generated by the navigationViewController.Return Value
A
Layer
after adjusted and will be added to the navigation view controller’s map view byMapboxNavigation
. -
navigationViewController(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)
Default implementationReturns an
CircleLayer
that marks the location of each destination along the route when there are multiple destinations. The returned layer is added to the map below the layer returned bynavigationViewController(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)
.If this method is unimplemented, the navigation view controller’s map view marks each destination waypoint with a circle.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, waypointCircleLayerWithIdentifier identifier: String, sourceIdentifier: String) -> CircleLayer?
Parameters
navigationViewController
The
NavigationViewController
object.identifier
The
CircleLayer
identifier.sourceIdentifier
Identifier of the source, which contains the waypoint data that this method would style.
Return Value
A
CircleLayer
that the map applies to all waypoints. -
navigationViewController(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)
Default implementationReturns a
SymbolLayer
that places an identifying symbol on each destination along the route when there are multiple destinations. The returned layer is added to the map above the layer returned bynavigationViewController(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)
.If this method is unimplemented, the navigation view controller’s map view labels each destination waypoint with a number, starting with 1 at the first destination, 2 at the second destination, and so on.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, waypointSymbolLayerWithIdentifier identifier: String, sourceIdentifier: String) -> SymbolLayer?
Parameters
navigationViewController
The
NavigationViewController
object.identifier
The
SymbolLayer
identifier.sourceIdentifier
Identifier of the source, which contains the waypoint data that this method would style.
Return Value
A
SymbolLayer
that the map applies to all waypoint symbols. -
navigationViewController(_:shapeFor:legIndex:)
Default implementationReturns a
FeatureCollection
that represents the destination waypoints along the route (that is, excluding the origin).If this method is unimplemented, the navigation view controller’s map view draws the waypoints using default
FeatureCollection
.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, shapeFor waypoints: [Waypoint], legIndex: Int) -> FeatureCollection?
Parameters
navigationViewController
The
NavigationViewController
object.waypoints
The waypoints to be displayed on the map.
legIndex
Return Value
Optionally, a
FeatureCollection
that defines the shape of the waypoint, ornil
to use default behavior. -
navigationViewController(_:roadNameAt:)
Default implementationCalled to allow the delegate to customize the contents of the road name label that is displayed towards the bottom of the map view.
This method is called on each location update. By default, the label displays the name of the road the user is currently traveling on.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, roadNameAt location: CLLocation) -> String?
Parameters
navigationViewController
The navigation view controller that will display the road name.
location
The user’s current location.
Return Value
The road name to display in the label, or nil to hide the label.
-
navigationViewController(_:shouldDiscard:)
Default implementationAllows the delegate to decide whether to ignore a location update.
This method is called on every location update. By default, the navigation view controller ignores certain location updates that appear to be unreliable, as determined by the
CLLocation.isQualified
property.Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, shouldDiscard location: CLLocation) -> Bool
Parameters
navigationViewController
The navigation view controller that discarded the location.
location
The location that will be discarded.
Return Value
If
true
, the location is discarded and theNavigationViewController
will not consider it. Iffalse
, the location will not be thrown out. -
navigationViewController(_:didSubmitArrivalFeedback:)
Default implementationCalled to notify that the user submitted the end of route feedback.
Default Implementation
UnimplementedLogging
prints a warning to standard output the first time this method is called.Declaration
Swift
func navigationViewController(_ navigationViewController: NavigationViewController, didSubmitArrivalFeedback feedback: EndOfRouteFeedback)
Parameters
navigationViewController
The
NavigationViewController
object.feedback
The
EndOfRouteFeedback
that was submitted by the user.