Core Navigation Logic

A navigation service coordinates various nonvisual components that track the user as they navigate along a predetermined route. You use MapboxNavigationService, which conforms to this protocol, either as part of NavigationViewController or by itself as part of a custom user interface. A navigation service calls methods on its delegate, which conforms to the NavigationServiceDelegate protocol, whenever significant events or decision points occur along the route.

A navigation service controls a NavigationLocationManager for determining the user’s location, a Router that tracks the user’s progress along the route, a MapboxRoutingProvider service for calculating new routes (only used when rerouting), and a NavigationEventsManager for sending telemetry events related to navigation or user feedback.

NavigationViewController comes with a MapboxNavigationService by default. You may override it to customize the MapboxRoutingProvider‘s source service or simulation mode. After creating the navigation service, pass it into NavigationOptions(styles:navigationService:voiceController:topBanner:bottomBanner:), then pass that object into NavigationViewController(for:options:).

If you use a navigation service by itself, outside of NavigationViewController, call start() when the user is ready to begin navigating along the route.

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.

A concrete implementation of the NavigationService protocol.

NavigationViewController comes with a MapboxNavigationService by default. You may override it to customize the Directions service or simulation mode. After creating the navigation service, pass it into NavigationOptions(styles:navigationService:voiceController:topBanner:bottomBanner:), then pass that object into NavigationViewController(for:options:).

If you use a navigation service by itself, outside of NavigationViewController, call start() when the user is ready to begin navigating along the route.

A class conforming to the Router protocol tracks the user’s progress as they travel along a predetermined route. It calls methods on its delegate, which conforms to the RouterDelegate protocol, whenever significant events or decision points occur along the route. Despite its name, this protocol does not define the interface of a routing engine.

There are two concrete implementations of the Router protocol. RouteController, the default implementation, is capable of client-side routing and depends on the Mapbox Navigation Native framework. LegacyRouteController is an alternative implementation that does not have this dependency but must be used in conjunction with the Mapbox Directions API over a network connection.

A router data source, also known as a location manager, supplies location data to a Router instance. For example, a MapboxNavigationService supplies location data to a RouteController or LegacyRouteController.

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.

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.

RouteProgress stores the user’s progress along a route.

RouteLegProgress stores the user’s progress along a route leg.

RouteStepProgress stores the user’s progress along a route step.

The VisualInstructionDelegate protocol defines a method that allows an object to customize presented visual instructions.

The NavigationEventsManager is responsible for being the liaison between MapboxCoreNavigation and the Mapbox telemetry.

The ActiveNavigationEventsManagerDataSource protocol declares values required for recording route following events.

A data source that declares values required for recording passive location events.

NavigationLocationManager is the base location manager which handles permissions and background modes.

ReplayLocationManager replays an array of locations exactly as they were recorded with the single exception of the location’s timestamp which will be adjusted by interval between locations.

The SimulatedLocationManager class simulates location updates along a given route.

The route will be replaced upon a RouteControllerDidReroute notification.

The manager calls delegate methods on a background thread.

A NavigationRouteOptions object specifies turn-by-turn-optimized criteria for results returned by the Mapbox Directions API.

NavigationRouteOptions is a subclass of RouteOptions that has been optimized for navigation. Pass an instance of this class into the Directions.calculate(_:completionHandler:) method.

This class implements the NSCopying protocol by round-tripping the object through JSONEncoder and JSONDecoder. If you subclass NavigationRouteOptions, make sure any properties you add are accounted for in Decodable(from:) and Encodable.encode(to:). If your subclass contains any customizations that cannot be represented in JSON, make sure the subclass overrides NSCopying.copy(with:) to persist those customizations.

NavigationRouteOptions is designed to be used with the Directions and NavigationDirections classes for specifying routing criteria. To customize the user experience in a NavigationViewController, use the NavigationOptions class.

A NavigationMatchOptions object specifies turn-by-turn-optimized criteria for results returned by the Mapbox Map Matching API.

NavigationMatchOptions is a subclass of MatchOptions that has been optimized for navigation. Pass an instance of this class into the Directions.calculateRoutes(matching:completionHandler:). method.

Note: it is very important you specify the waypoints for the route. Usually the only two values for this IndexSet will be 0 and the length of the coordinates. Otherwise, all coordinates passed through will be considered waypoints.

The simulation mode type. Used for setting the simulation mode of the navigation service.

The simulation intent type. Used for describing the intent to start simulation of the navigation service.

The simulation state type. Used for notifying users of the change of navigation service simulation status.

An object that notifies its delegate when the user’s location changes, minimizing the noise that normally accompanies location updates from a CLLocationManager object.

Unlike Router classes such as RouteController and LegacyRouteController, this class operates without a predefined route, matching the user’s location to the road network at large. You can use a passive location manager to determine a starting point for a route that you calculate using the Directions.calculate(_:completionHandler:) method. If the user happens to be moving while you calculate the route, the passive location manager makes it less likely that the route will begin with a short segment on a side road or driveway and a confusing instruction to turn onto the current road.

To find out when the user’s location changes, implement the PassiveLocationManagerDelegate protocol, or observe Notification.Name.passiveLocationManagerDidUpdate notifications for more detailed information.

A delegate of a PassiveLocationManager object implements methods that the location manager calls as the user’s location changes.