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.

Monitoring Route Progress


                    
                    
                    navigationViewControllerDidDismiss(_:byCanceling:)

Default implementation

Called 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didUpdate:with:rawLocation:)

Default implementation

Called 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didAdd:pointAnnotationManager:)

Default implementation

Tells the receiver that the final destination PointAnnotation was added to the NavigationViewController.

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.

View Source on GitHub


                    
                    
                    navigationViewController(_:willArriveAt:after:distance:)

Default implementation

Called 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didArriveAt:)

Default implementation

Called 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 return false within this method, you must manually advance to the next leg using the Router.advanceLegIndex(completionHandler:) method. Obtain Router via the NavigationViewController.navigationService and NavigationService.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.

View Source on GitHub

Rerouting and Refreshing the Route


                    
                    
                    navigationViewController(_:shouldRerouteFrom:)

Default implementation

Returns 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:shouldPreventReroutesWhenArrivingAt:)

Default implementation

Called 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

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.

View Source on GitHub


                    
                    
                    navigationViewController(_:willRerouteFrom:)

Default implementation

Called 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 the Notification.Name.routeControllerWillReroute notification being posted, and before navigationViewController(_:didRerouteAlong:) 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didRerouteAlong:)

Default implementation

Called immediately after the navigation view controller receives a new route.

This method is called after navigationViewController(_:willRerouteFrom:) and simultaneously with the Notification.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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didFailToRerouteWith:)

Default implementation

Called when the navigation view controller fails to receive a new route.

This method is called after navigationViewController(_:willRerouteFrom:) and simultaneously with the Notification.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.

View Source on GitHub


                    
                    
                    navigationViewController(_:didRefresh:)

Default implementation

Called 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.

View Source on GitHub

Customizing the Route Elements


                    
                    
                    navigationViewController(_:routeLineLayerWithIdentifier:sourceIdentifier:)

Default implementation

Returns 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:routeCasingLineLayerWithIdentifier:sourceIdentifier:)

Default implementation

Returns 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:routeRestrictedAreasLineLayerWithIdentifier:sourceIdentifier:)

Default implementation

Returns 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.

View Source on GitHub


                    
                    
                    navigationViewController(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)

Default implementation

Returns 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 by navigationViewController(_: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.

View Source on GitHub


                    
                    
                    navigationViewController(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)

Default implementation

Returns 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 by navigationViewController(_: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.

View Source on GitHub


                    
                    
                    navigationViewController(_:shapeFor:legIndex:)

Default implementation

Returns 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`	Index, which determines for which `RouteLeg` `Waypoint` will be shown.

Return Value

Optionally, a FeatureCollection that defines the shape of the waypoint, or nil to use default behavior.

View Source on GitHub


                    
                    
                    navigationViewController(_:roadNameAt:)

Default implementation

Called 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.

View Source on GitHub

Filtering Location Updates


                    
                    
                    navigationViewController(_:shouldDiscard:)

Default implementation

Allows 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 the NavigationViewController will not consider it. If false, the location will not be thrown out.

View Source on GitHub

navigationViewController(_:didSelect:) Extension method
UnimplementedLogging prints a warning to standard output the first time this method is called.
Declaration
Swift

func navigationViewController(_ navigationViewController: NavigationViewController, didSelect route: Route)
View Source on GitHub