RouterDelegate

 
public protocol RouterDelegate : AnyObject, UnimplementedLogging

A router delegate interacts with one or more Router instances, such as RouteController objects, during turn-by-turn navigation. This protocol is similar to NavigationServiceDelegate, which is the main way that your application can synchronize its state with the SDK’s location-related functionality. Normally, you should not need to make a class conform to the RouterDelegate protocol or call any of its methods directly, but you would need to call this protocol’s methods if you implement a custom Router class.

MapboxNavigationService is the only concrete implementation of a router delegate. Implement the NavigationServiceDelegate protocol instead to be notified when various significant events occur along the route tracked by a NavigationService.

Seealso

MapboxNavigationService

Seealso

NavigationServiceDelegate

Rerouting Logic
  • router(_:shouldRerouteFrom:) Default implementation

    Returns whether the router should be allowed to calculate a new route.

    If implemented, this method is called as soon as the router detects that the user is off the predetermined route. Implement this method to conditionally prevent rerouting. If this method returns true, router(_:willRerouteFrom:) will be called immediately afterwards.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, shouldRerouteFrom location: CLLocation) -> Bool

    Parameters

    router

    The router that has detected the need to calculate a new route.
    location

    The user’s current location.

    Return Value

    True to allow the router 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 router 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 router(_ router: Router, shouldProactivelyRerouteFrom location: CLLocation, to route: Route, completion: @escaping () -> Void)

    Parameters

    router

    The router that has detected faster new route
    location

    The user’s current location.
    route

    The route found.
    completion

    Completion to be called to allow the router to apply a new route; Ignoring calling the completion will ignore the faster route aswell.
    View Source on GitHub
  • router(_:willRerouteFrom:) Default implementation

    Called immediately before the router calculates a new route.

    This method is called after router(_:shouldRerouteFrom:) is called, and before router(_:modifiedOptionsForReroute:) is called.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, willRerouteFrom location: CLLocation)

    Parameters

    router

    The router that will calculate a new route.
    location

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

    When reroute is happening, router suggests to customize the RouteOptions used to calculate new route.

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

    Default implementation does no modifications.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, modifiedOptionsForReroute options: RouteOptions) -> RouteOptions

    Parameters

    router

    The router that will calculate a new route.
    options

    Original RouteOptions.

    Return Value

    Modified RouteOptions.

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

    • return: If true, the location is discarded and the Router will not consider it. If false, the location will not be thrown out.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, shouldDiscard location: CLLocation) -> Bool

    Parameters

    router

    The router that discarded the location.
    location

    The location that will be discarded.
    View Source on GitHub

  • Called immediately after the router receives a new route.

    This method is called after router(_:modifiedOptionsForReroute:) method is called.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didRerouteAlong route: Route, at location: CLLocation?, proactive: Bool)

    Parameters

    router

    The router that has calculated a new route.
    route

    The new route.
    View Source on GitHub

  • Called when router has detected a change in alternative routes list.

    Note

    LegacyRouteController will never report alternative routes updates.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didUpdateAlternatives updatedAlternatives: [AlternativeRoute], removedAlternatives: [AlternativeRoute])

    Parameters

    router

    The router 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 router has failed to change alternative routes list.

    Note

    LegacyRouteController will never report alternative routes updates.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didFailToUpdateAlternatives error: AlternativeRouteError)

    Parameters

    router

    The router reporting an update.
    error

    An error occured.
    View Source on GitHub

  • Called when router has detected user taking an alternative route.

    This method is called before updating router’s main route.

    LegacyRouteController never calls this method, because it cannot generate routes on the device.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, willTakeAlternativeRoute route: Route, at location: CLLocation?)

    Parameters

    router

    The router 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
  • router(_:didTakeAlternativeRouteAt:) Default implementation

    Called when router has finished switching to an alternative route

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

    Note

    LegacyRouteController will never report alternative routes updates.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didTakeAlternativeRouteAt location: CLLocation?)

    Parameters

    router

    The router that switched to the alternative.
    location

    The user’s current location.
    View Source on GitHub

  • Called when router has failed to take an alternative route.

    This method is called after router(_:willTakeAlternativeRoute:).

    This call would indicate that something went wrong during setting new main route.

    Note

    LegacyRouteController will never report alternative routes updates.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didFailToTakeAlternativeRouteAt location: CLLocation?)

    Parameters

    router

    The router which tried to switch to the alternative.
    location

    The user’s current location.
    View Source on GitHub

  • Called when router has automatically switched to the coincide online route.

    Note

    LegacyRouteController will never do that.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didSwitchToCoincidentOnlineRoute coincideRoute: Route)

    Parameters

    router

    The router reporting an update.
    coincideRoute

    A route taken.
    View Source on GitHub
  • router(_:didFailToRerouteWith:) Default implementation

    Called when the router fails to receive a new route.

    This method is called after router(_:modifiedOptionsForReroute:).

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didFailToRerouteWith error: Error)

    Parameters

    router

    The router 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

  • Called immediately after the router refreshes the route.

    Declaration

    Swift

    func router(_ router: Router, didRefresh routeProgress: RouteProgress)

    Parameters

    router

    The router that has refreshed the route.
    routeProgress

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

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

    Default Implementation

    Declaration

    Swift

    func routerDidFailToRefreshExpiredRoute(_ router: Router)

    Parameters

    router

    The router that attempted the route refresh.
    View Source on GitHub
  • router(_:didUpdate:with:rawLocation:) Default implementation

    Called when the router updates the route progress model.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didUpdate progress: RouteProgress, with location: CLLocation, rawLocation: CLLocation)

    Parameters

    router

    The router 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 router arrives at a waypoint.

    You can implement this method to allow the router to continue check and reroute the user if needed. By default, the user will not be rerouted when arriving at a waypoint.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, shouldPreventReroutesWhenArrivingAt waypoint: Waypoint) -> Bool

    Parameters

    router

    The router that has arrived at a waypoint.
    waypoint

    The waypoint that the controller has arrived at.

    Return Value

    True to prevent the router from checking if the user should be rerouted.

    View Source on GitHub

  • Called as the router 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

    Declaration

    Swift

    func router(_ router: Router, willArriveAt waypoint: Waypoint, after remainingTimeInterval: TimeInterval, distance: CLLocationDistance)

    Parameters

    router

    The router 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
  • router(_:didArriveAt:) Default implementation

    Called when the router arrives at a waypoint.

    You can implement this method to prevent the router 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 router 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

    Declaration

    Swift

    func router(_ router: Router, didArriveAt waypoint: Waypoint) -> Bool

    Parameters

    router

    The router 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 router detects that the user has passed a point at which an instruction should be displayed.

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didPassVisualInstructionPoint instruction: VisualInstructionBanner, routeProgress: RouteProgress)

    Parameters

    router

    The router that passed the instruction point.
    instruction

    The instruction to be presented.
    routeProgress

    The route progress object that the router is updating.
    View Source on GitHub

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

    Default Implementation

    Declaration

    Swift

    func router(_ router: Router, didPassSpokenInstructionPoint instruction: SpokenInstruction, routeProgress: RouteProgress)

    Parameters

    router

    The router that passed the instruction point.
    instruction

    The instruction to be spoken.
    routeProgress

    The route progress object that the router is updating.
    View Source on GitHub

Permissions Events

  • Called when the router will disable battery monitoring.

    Implementing this method will allow developers to change whether battery monitoring is disabled when the Router is deinited.

    Default Implementation

    Declaration

    Swift

    func routerShouldDisableBatteryMonitoring(_ router: Router) -> Bool

    Parameters

    router

    The router 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