RouteController Class Reference

RouteController

open class RouteController : NSObject

extension RouteController: HistoryRecording

extension RouteController: Router

A RouteController tracks the user’s progress along a route, posting notifications as the user reaches significant points along the route. On every location update, the route controller evaluates the user’s location, determining whether the user remains on the route. If not, the route controller calculates a new route.

RouteController is responsible for the core navigation logic whereas NavigationViewController is responsible for displaying a default drop-in navigation UI.

Important

Creating an instance of this type will start an Active Guidance session. The trip session is stopped when the instance is deallocated. From more info read the Pricing Guide.

Precondition

There should be only one RouteController alive to any given time.

DefaultBehavior
See more
Declaration
Swift

public enum DefaultBehavior
View Source on GitHub

navigatorTileStore
A TileStore instance used by navigator
Declaration
Swift

open var navigatorTileStore: TileStore { get }
View Source on GitHub
dataSource
The route controller’s associated location manager.
Declaration
Swift

public unowned var dataSource: RouterDataSource
View Source on GitHub


                    
                    
                    directions

A reference to a MapboxDirections service. Used for rerouting.

Declaration

Swift

@available(*, deprecated, message: "Use `customRoutingProvider` instead. If route controller was not initialized using `Directions` object - this property is unused and ignored.")
public lazy var directions: Directions { get set }

View Source on GitHub


                    
                    
                    routingProvider

RoutingProvider, used to create a route during refreshing or rerouting.

Declaration

Swift

@available(*, deprecated, message: "Use `customRoutingProvider` instead. This property will be equal to `customRoutingProvider` if that is provided or a `MapboxRoutingProvider` instance otherwise.")
public lazy var routingProvider: RoutingProvider { get set }

View Source on GitHub

customRoutingProvider
Custom RoutingProvider, used to create a route during refreshing or rerouting.

If set to nil - default Mapbox implementation will be used.
Declaration
Swift

public var customRoutingProvider: RoutingProvider?
View Source on GitHub
route
Declaration
Swift

public var route: Route { get }
View Source on GitHub


                    
                    
                    indexedRouteResponse

Declaration

Swift

public internal(set) var indexedRouteResponse: IndexedRouteResponse { get set }

View Source on GitHub

Tracking the Progress

routeProgress
Details about the user’s progress along the current route, leg, and step.

To advance the route progress to next leg, use RouteController.advanceLegIndex(completionHandler:) method.
Declaration
Swift

public private(set) var routeProgress: RouteProgress { get }
View Source on GitHub
location
The idealized user location. Snapped to the route line, if applicable, otherwise raw.

See also
snappedLocation, rawLocation
Declaration
Swift

public var location: CLLocation? { get }
View Source on GitHub
rawLocation
The most recently received user location.

Note
This is a raw location received from locationManager. To obtain an idealized location, use the location property.
Declaration
Swift

public var rawLocation: CLLocation? { get set }
View Source on GitHub
delegate
The route controller’s delegate.
Declaration
Swift

public weak var delegate: RouterDelegate?
View Source on GitHub
heading
The route controller’s heading.
Declaration
Swift

public var heading: CLHeading?
View Source on GitHub


                    
                    
                    advanceLegIndex(completionHandler:)

Advances current RouteProgress.legIndex by 1.

Declaration

Swift

public func advanceLegIndex(completionHandler: AdvanceLegCompletionHandler? = nil)

Parameters


                                  completionHandler

Completion handler, which is called to report a status whether RouteLeg was changed or not.

View Source on GitHub


                    
                    
                    startUpdatingElectronicHorizon(with:)

Starts electronic horizon updates.

Pass nil to use the default configuration. Updates will be delivered in Notification.Name.electronicHorizonDidUpdatePosition notification. For more info, read the Electronic Horizon Guide.

Postcondition

To change electronic horizon options call this method again with new options.

Note

The Mapbox Electronic Horizon feature of the Mapbox Navigation SDK is in public beta and is subject to changes, including its pricing. Use of the feature is subject to the beta product restrictions in the Mapbox Terms of Service. Mapbox reserves the right to eliminate any free tier or free evaluation offers at any time and require customers to place an order to purchase the Mapbox Electronic Horizon feature, regardless of the level of use of the feature.

Declaration

Swift

public func startUpdatingElectronicHorizon(with options: ElectronicHorizonOptions? = nil)

Parameters


                                  options

Options which will be used to configure electronic horizon updates.

View Source on GitHub

stopUpdatingElectronicHorizon()
Stops electronic horizon updates.
Declaration
Swift

public func stopUpdatingElectronicHorizon()
View Source on GitHub

Controlling and Altering the Route

reroutesProactively
Declaration
Swift

public var reroutesProactively: Bool
View Source on GitHub


                    
                    
                    initialManeuverAvoidanceRadius

Declaration

Swift

public var initialManeuverAvoidanceRadius: TimeInterval { get set }

View Source on GitHub

refreshesRoute
Controls whether the route controller automatically updates ETA and traffic congestion data.

When enabled, the route controller periodically refreshes route information at intervals defined by RouteControllerProactiveReroutingInterval. By default, route refreshing is enabled only for routes using .automobileAvoidingTraffic or another driving-traffic profile. If reroutesProactively is also enabled, the route controller runs the rerouting check after the route refresh completes.

Important
Route refresh is currently supported only for driving-traffic profiles. Enabling this property for other profiles (such as walking, cycling, or standard driving) may result in server errors or undefined behavior.
Declaration
Swift

public var refreshesRoute: Bool { get set }
View Source on GitHub


                    
                    
                    continuousAlternatives

Declaration

Swift

public private(set) var continuousAlternatives: [AlternativeRoute] { get }

View Source on GitHub

prefersOnlineRoute
Enables automatic switching to online version of the current route when possible.

Indicates if RouteController will attempt to detect if current route was build offline and if there is an online route with the same path is available to automatically switch to it. Using online route is beneficial due to available live data like traffic congestion, incidents, etc. Check is not performed instantly and it is not guaranteed to receive an online version at any given period of time.

Enabled by default.
Declaration
Swift

public var prefersOnlineRoute: Bool
View Source on GitHub

Navigating


                    
                    
                    locationManager(_:didUpdateLocations:)

Declaration

Swift

public func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation])

View Source on GitHub


                    
                    
                    locationManager(_:didUpdateHeading:)

Declaration

Swift

public func locationManager(_ manager: CLLocationManager, didUpdateHeading newHeading: CLHeading)

View Source on GitHub


                    
                    
                    updateRouteLeg(to:completionHandler:)

Updates current RouteProgress.legIndex to specified leg index.

Declaration

Swift

public func updateRouteLeg(to index: Int, completionHandler: AdvanceLegCompletionHandler? = nil)

Parameters

`index`	Leg index value to set.
`completionHandler`	Completion handler, which is called to report a status whether `RouteLeg` was changed or not.

View Source on GitHub

finishRouting()
Declaration
Swift

public func finishRouting()
View Source on GitHub

Handling Lifecycle


                    
                    
                    init(alongRouteAtIndex:in:options:directions:dataSource:)

Declaration

Swift

public convenience init(alongRouteAtIndex routeIndex: Int, in routeResponse: RouteResponse, options: RouteOptions, directions: Directions = NavigationSettings.shared.directions, dataSource source: RouterDataSource)

View Source on GitHub


                    
                    
                    init(alongRouteAtIndex:in:options:routingProvider:dataSource:)

Declaration

Swift

@available(*, deprecated, renamed: "init(indexedRouteResponse:customRoutingProvider:dataSource:﹚")
required public convenience init(alongRouteAtIndex routeIndex: Int,
                                 in routeResponse: RouteResponse,
                                 options: RouteOptions,
                                 routingProvider: RoutingProvider,
                                 dataSource source: RouterDataSource)

View Source on GitHub


                    
                    
                    init(alongRouteAtIndex:in:options:customRoutingProvider:dataSource:)

Declaration

Swift

@available(*, deprecated, renamed: "init(indexedRouteResponse:customRoutingProvider:dataSource:﹚")
required public convenience init(alongRouteAtIndex routeIndex: Int,
                                 in routeResponse: RouteResponse,
                                 options: RouteOptions,
                                 customRoutingProvider: RoutingProvider? = nil,
                                 dataSource source: RouterDataSource)

View Source on GitHub


                    
                    
                    init(indexedRouteResponse:customRoutingProvider:dataSource:)

Declaration

Swift

required public init(indexedRouteResponse: IndexedRouteResponse,
                     customRoutingProvider: RoutingProvider?,
                     dataSource source: RouterDataSource)

View Source on GitHub

Accessing Relevant Routing Data

roadGraph
The road graph that is updated as the route controller tracks the user’s location.
Declaration
Swift

public var roadGraph: RoadGraph { get }
View Source on GitHub
roadObjectStore
The road object store that is updated as the route controller tracks the user’s location.
Declaration
Swift

public var roadObjectStore: RoadObjectStore { get }
View Source on GitHub
roadObjectMatcher
The road object matcher that allows to match user-defined road objects.
Declaration
Swift

public var roadObjectMatcher: RoadObjectMatcher { get }
View Source on GitHub

Congestion Level Default Ranges

NotificationUserInfoKey
Keys in the user info dictionaries of various notifications posted by instances of RouteController.
See more
Declaration
Swift

public struct NotificationUserInfoKey : Hashable, Equatable, RawRepresentable
View Source on GitHub

Controlling and Altering the Route


                    
                    
                    userIsOnRoute(_:)

Declaration

Swift

public func userIsOnRoute(_ location: CLLocation) -> Bool

View Source on GitHub


                    
                    
                    userIsOnRoute(_:status:)

Declaration

Swift

public func userIsOnRoute(_ location: CLLocation, status: NavigationStatus?) -> Bool

View Source on GitHub


                    
                    
                    reroute(from:along:)

Declaration

Swift

public func reroute(from location: CLLocation, along progress: RouteProgress)

View Source on GitHub


                    
                    
                    updateRoute(with:routeOptions:completion:)

Declaration

Swift

public func updateRoute(with indexedRouteResponse: IndexedRouteResponse,
                        routeOptions: RouteOptions?,
                        completion: ((Bool) -> Void)?)

View Source on GitHub