MapboxNavigation.swift

Example app guiding the user along a route

MapboxNavigation.swift provides an API to add turn by turn navigation to your app. The basic workflow of how it fits into your app:

1. Provide RouteController with a route
2. Start the RouteController with resume() when the user should enter guidance mode
3. MapboxNavigation.swift will then emit NSNotification when:

• The use makes progress along the route
• The user should be alerted about an upcoming maneuver
• The user should be rerouted

1. Depending on what is emitted, your app should react accordingly

A simple implementation can be viewed in the example app — available in Objective-C or Swift.

Installation options

CocoaPods

You'll need to install two pods, MapboxNavigation.swift and MapboxDirections.swift

Add the following lines to your Podfile:

pod 'MapboxDirections.swift', :git => 'https://github.com/mapbox/MapboxDirections.swift.git', :commit => 'ceaf58b780fc17ea44a9150041b602d017c1e567'
pod 'MapboxNavigation.swift', :git => 'https://github.com/mapbox/MapboxNavigation.swift.git', :tag => 'v0.0.4'

Carthage

Add the following line to your Cartfile:

github "mapbox/MapboxNavigation.swift"

Gist of how this works

RouteController is given a route. Internally, MapboxNavigation.swift is comparing the route to the users location and looking at 3 principle pieces:

1. Is the user on or off the route?
2. How far along the step is the user?
3. Does the user need to be alerted about an upcoming maneuver?

The library compares the user from the route and decides upon each one of these parameters and acts accordingly. The developer is told what is happening behind the scenes via NSNotification.

Notifications

This library relies heavily on the class NSNotification for letting the developer know when events have occurred.

RouteControllerProgressDidChange

• Emitted when the user moves along the route. Notification contains 3 keys:
  • RouteControllerProgressDidChangeNotificationProgressKey - RouteProgress - Current progress along route
  • RouteControllerProgressDidChangeNotificationLocationKey - CLLocation - Current location
  • RouteControllerProgressDidChangeNotificationSecondsRemainingOnStepKey - Double - Given users speed and location, this is the number of seconds left to the end of the step

RouteControllerAlertLevelDidChange

• Emitted when the alert level changes. This indicates the user should be notified about the upcoming maneuver. See [Alerts](#Alert levels). Notification contains 3 keys:
  • RouteControllerProgressDidChangeNotificationProgressKey - RouteProgress - Current progress along route
  • RouteControllerAlertLevelDidChangeNotificationDistanceToEndOfManeuverKey - CLLocationDistance - The users snapped distance to the end of the route.

RouteControllerShouldReroute

• Emitted when the user is off the route and should be rerouted. Notification contains 1 key:
  • RouteControllerNotificationShouldRerouteKey - CLLocation - Last location of user

Alert levels

Alert levels indicate the type of announcement that should be given. The enum types available are:

• none
• depart - Emitted while departing origin
• low - Emitted directly after completing the maneuver
• medium - Emitted when the user has 70 seconds remaining on the route.
• high - Emitted when the user has 15 seconds remaining on the route.
• arrive - Emitted when the user arrives at destination

Rerouting

In the event of a reroute, it's necessary to update the current route with a new route. Once fetched, you can update the current route by:

navigation.routeProgress = RouteProgress(route: newRoute)

Examples

We provide examples in Swift and Objective-C. Run pod install from the Example folder and open Example.xcworkspace to try it out.

Running the example app

1. If running in the simulator, you can simulate the user location by selecting Debug -> Location -> City Bicycle Ride
2. Long press any where on a map. This is where you will be routed to.
3. Press Start Navigation to begin
4. Press Stop Navigation to end

---

MapboxNavigationUI.swift

MapboxNavigationUI.swift makes it easy for developers to add turn-by-turn navigation to their iOS application.

Examples

We provide examples in Swift and Objective-C. Run carthage update --platform ios from the root folder and open Example/Example.xcworkspace to try it out.

Instantiating a navigation UI (RouteViewController)

let viewController = NavigationUI.routeViewController(for: route, directions: directions)
present(viewController, animated: true, completion: nil)

• route the initial route you want to navigate.
• directions a Direction instance needed for re-routing when the user goes off route.

Basic styling

Installation options

CocoaPods

You'll need to install three pods, MapboxNavigationUI.swift, MapboxNavigation.swift and MapboxDirections.swift

Add the following lines to your Podfile:

pod 'MapboxDirections.swift', :git => 'https://github.com/mapbox/MapboxDirections.swift.git', :commit => 'ceaf58b780fc17ea44a9150041b602d017c1e567'
pod 'MapboxNavigation.swift', :git => 'https://github.com/mapbox/MapboxNavigation.swift.git', :tag => 'v0.0.4'
pod 'MapboxNavigationUI.swift', :git => 'https://github.com/mapbox/MapboxNavigation.swift.git', :tag => 'v0.0.4'

Carthage

1: Add the following line to your Cartfile:

github "mapbox/MapboxNavigation.swift"

2: Run:

carthage update --platform ios

3: Drag all frameworks (located in Carthage/Build/iOS) into Embedded Frameworks.