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

  • 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

  • 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

Interaction With Waypoints

  • 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
    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

  • 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

  • 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

  • Tells 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
    waypoint

    The waypoint that was selected.
    View Source on GitHub

Rerouting and Refreshing the Route

  • 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

  • Asks 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 to true (default). Calling provided completion 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.
    View Source on GitHub

  • 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

    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.

    View Source on GitHub

  • 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(_: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.
    View Source on GitHub

  • When 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 before navigationViewController(_: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.

    View Source on GitHub

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

    This method is called after navigationViewController(_:modifiedOptionsForReroute:) 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

  • Called 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.
    View Source on GitHub

  • Called 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.
    View Source on GitHub

  • Called 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.
    View Source on GitHub

  • Called 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.
    View Source on GitHub

  • Called 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.
    View Source on GitHub

  • Called 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.
    View Source on GitHub

  • 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
    continuousAlternative

    The route that was selected.
    View Source on GitHub

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

    This method is called after navigationViewController(_:modifiedOptionsForReroute:) 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

  • 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

  • Called immediately after the navigation view controller attempted to refresh the route, but failed due to expired route TTL.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func navigationViewControllerDidFailToRefreshExpiredRoute(_ navigationViewController: NavigationViewController)

    Parameters

    navigationViewController

    The navigation view controller that attempted the route refresh.
    View Source on GitHub

Customizing the Route Elements

Filtering Location Updates

  • 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

  • Called 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
    feedback

    The EndOfRouteFeedback that was submitted by the user.
    View Source on GitHub