NavigationServiceDelegate

 
public protocol NavigationServiceDelegate : AnyObject, UnimplementedLogging

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

NavigationViewControllerDelegate

Seealso

RouterDelegate

Rerouting Logic

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

    Default Implementation

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

    Declaration

    Swift

    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.

    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 service 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 navigationService(_ service: NavigationService, shouldProactivelyRerouteFrom location: CLLocation, to route: Route, completion: @escaping () -> Void)

    Parameters

    service

    The navigation service 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 service to apply a new route; Ignoring calling the completion will ignore the faster route aswell.
    View Source on GitHub
  • navigationService(_:willRerouteFrom:) Default implementation

    Called immediately before the navigation service calculates a new route.

    This method is called after navigationService(_:shouldRerouteFrom:) is called, simultaneously with the Notification.Name.routeControllerWillReroute notification being posted, and before navigationService(_:modifiedOptionsForReroute:) is called.

    Default Implementation

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

    Declaration

    Swift

    func navigationService(_ service: NavigationService, willRerouteFrom location: CLLocation)

    Parameters

    service

    The navigation service that will calculate a new route.
    location

    The user’s current location.
    View Source on GitHub

  • When reroute is happening, navigation service suggests to customize the RouteOptions used to calculate new route.

    This method is called after navigationService(_:willRerouteFrom:) is called, and before navigationService(_:didRerouteAlong:) is called. This method is not called on proactive rerouting.

    Default implementation does no modifications.

    Default Implementation

    Declaration

    Swift

    func navigationService(_ service: NavigationService, modifiedOptionsForReroute options: RouteOptions) -> RouteOptions

    Parameters

    service

    The navigation service that will calculate a new route.
    options

    Original RouteOptions.

    Return Value

    Modified RouteOptions.

    View Source on GitHub

  • Called when navigation service 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 navigationService(_ service: NavigationService, didUpdateAlternatives updatedAlternatives: [AlternativeRoute], removedAlternatives: [AlternativeRoute])

    Parameters

    service

    The navigation service 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 service 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 navigationService(_ service: NavigationService, didFailToUpdateAlternatives error: AlternativeRouteError)

    Parameters

    service

    The navigation service reporting an update.
    error

    An error occured.
    View Source on GitHub

  • Called when navigation service 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 navigationService(_ service: NavigationService, didSwitchToCoincidentOnlineRoute coincideRoute: Route)

    Parameters

    service

    The navigation service reporting an update.
    coincideRoute

    A route taken.
    View Source on GitHub

  • Called when navigation service 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 navigationService(_ service: NavigationService, willTakeAlternativeRoute route: Route, at location: CLLocation?)

    Parameters

    service

    The navigation service 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 service has finished switching to an alternative route

    This method is called after navigationService(_:willTakeAlternativeRoute:)

    Default Implementation

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

    Declaration

    Swift

    func navigationService(_ service: NavigationService, didTakeAlternativeRouteAt location: CLLocation?)

    Parameters

    service

    The navigation service that switched to the alternative.
    location

    The user’s current location.
    View Source on GitHub

  • Called when navigation service has failed to take an alternative route.

    This method is called after navigationService(_: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 navigationService(_ service: NavigationService, didFailToTakeAlternativeRouteAt location: CLLocation?)

    Parameters

    service

    The navigation service which tried to switch to the alternative.
    location

    The user’s current location.
    View Source on GitHub
  • navigationService(_:shouldDiscard:) Default implementation

    Called when a location has been identified as unqualified to navigate on.

    See CLLocation.isQualified for more information about what qualifies a location.

    Default Implementation

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

    Declaration

    Swift

    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 Value

    If true, the location is discarded and the NavigationService will not consider it. If false, the location will not be thrown out.

    View Source on GitHub

  • Called immediately after the navigation service receives a new route.

    This method is called after navigationService(_: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 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.
    View Source on GitHub

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

    This method is called after navigationService(_: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 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.
    View Source on GitHub

Monitoring Route Progress and Updates
  • navigationService(_:didRefresh:) Default implementation

    Called immediately after the navigation service 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 navigationService(_ service: NavigationService, didRefresh routeProgress: RouteProgress)

    Parameters

    service

    The navigation service that has refreshed the route.
    routeProgress

    The route progress updated with the refreshed route.
    View Source on GitHub

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

    Default Implementation

    Declaration

    Swift

    func navigationServiceDidFailToRefreshExpiredRoute(_ service: NavigationService)

    Parameters

    service

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

  • Called when the navigation service updates the route progress model.

    Default Implementation

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

    Declaration

    Swift

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

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

    Default Implementation

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

    Declaration

    Swift

    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.

    View Source on GitHub

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

    Default Implementation

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

    Declaration

    Swift

    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.
    View Source on GitHub
  • navigationService(_:didArriveAt:) Default implementation

    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 using Router.advanceLegIndex(completionHandler:) method.

    Default Implementation

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

    Declaration

    Swift

    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.

    View Source on GitHub

  • Called when the navigation service detects that the user has passed a point at which an instruction should be displayed.

    Default Implementation

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

    Declaration

    Swift

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

  • Called when the navigation service detects that the user has passed a point at which an instruction should be spoken.

    Default Implementation

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

    Declaration

    Swift

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

Permissions Events

  • Called when the location manager’s accuracy authorization changed.

    You can implement this method to allow the navigation service to check if the user changed accuracy authorization, especially if reducedAccuracy is enabled. This method is only relevant for iOS 14 and above.

    Default Implementation

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

    Declaration

    Swift

    func navigationServiceDidChangeAuthorization(_ service: NavigationService, didChangeAuthorizationFor locationManager: CLLocationManager)

    Parameters

    service

    The navigation service that will alert that user that reducedAccuracy is enabled.
    manager

    The location manager.
    View Source on GitHub

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

    Default Implementation

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

    Declaration

    Swift

    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.

    View Source on GitHub

Simulating a Route

  • 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 a “Poor GPS” banner in the UI.

    Default Implementation

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

    Declaration

    Swift

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

  • 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 a “Poor GPS” banner in the UI.

    Default Implementation

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

    Declaration

    Swift

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

  • 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 a “Poor GPS” banner in the UI.

    Default Implementation

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

    Declaration

    Swift

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

  • 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 a “Poor GPS” banner in the UI.

    Default Implementation

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

    Declaration

    Swift

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