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
  • 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(_:didRerouteAlong:) 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(_: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(_:willRerouteFrom:) 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
  • router(_:didFailToRerouteWith:) Default implementation

    Called when the router fails to receive a new route.

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

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