Mapbox Navigation SDK for iOS
The Mapbox Navigation SDK gives you all the tools you need to add turn-by-turn navigation to your application. It takes just a few minutes to drop a full-fledged turn-by-turn navigation view controller into your application. Or use the Core Navigation framework directly to build something truly custom.
The Mapbox Navigation SDK and Core Navigation are compatible with applications written in Swift 4 or Objective-C in Xcode 9.0. The Mapbox Navigation framework runs on iOS 9.0 and above, while the Core Navigation framework runs on iOS 8.0 and above.
Installation
Using CocoaPods
To install Mapbox Navigation using CocoaPods:
Create a Podfile with the following specification:
pod 'MapboxNavigation', '~> 0.17'
Run
pod repo update && pod install
and open the resulting Xcode workspace.
Using Carthage
Alternatively, to install Mapbox Navigation using Carthage:
Create a Cartfile with the following dependency:
github "mapbox/mapbox-navigation-ios" ~> 0.17
Run
carthage update --platform iOS
to build just the iOS dependencies.Follow the rest of Carthage’s iOS integration instructions. Your application target’s Embedded Frameworks should include MapboxNavigation.framework and MapboxCoreNavigation.framework.
Configuration
Mapbox APIs and vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom iOS Target Properties” section, set
MGLMapboxAccessToken
to your access token. You can obtain an access token from the Mapbox account page.In order for the SDK to track the user’s location as they move along the route, set
NSLocationWhenInUseUsageDescription
to:Shows your location on the map and helps improve OpenStreetMap.
Users expect the SDK to continue to track the user’s location and deliver audible instructions even while a different application is visible or the device is locked. Go to the Capabilities tab. Under the Background Modes section, enable “Audio, AirPlay, and Picture in Picture” and “Location updates”. (Alternatively, add the
audio
andlocation
values to theUIBackgroundModes
array in the Info tab.)
Now import the relevant modules and present a new NavigationViewController
. You can also push to a navigation view controller from within a storyboard if your application’s UI is laid out in Interface Builder.
import MapboxDirections
import MapboxCoreNavigation
import MapboxNavigation
let origin = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.9131752, longitude: -77.0324047), name: "Mapbox")
let destination = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.8977, longitude: -77.0365), name: "White House")
let options = NavigationRouteOptions(waypoints: [origin, destination])
Directions.shared.calculate(options) { (waypoints, routes, error) in
guard let route = routes?.first else { return }
let viewController = NavigationViewController(for: route)
present(viewController, animated: true, completion: nil)
}
Starting points
This SDK is divided into two frameworks: the Mapbox Navigation framework (MapboxNavigation
) is the ready-made turn-by-turn navigation UI, while the Mapbox Core Navigation framework (MapboxCoreNavigation
) is responsible for the underlying navigation logic.
Mapbox Navigation
NavigationViewController
is the main class that encapsulates the entirety of the turn-by-turn navigation UI, orchestrating the map view, various UI elements, and the route controller. Your application would most likely present an instance of this class. The NavigationViewControllerDelegate
protocol allows your application to customize various aspects of the UI and react to location-related events as they occur.
NavigationMapView
is the map view at the center of the turn-by-turn navigation UI. You can also use this class independently of NavigationViewController
, for example to display a route preview map. The NavigationMapViewDelegate
protocol allows your application to customize various aspects of the map view’s appearance.
Core Navigation
RouteController
is responsible for receiving user location updates and determining their relation to the route line. If you build a completely custom navigation UI, this is the class your code would interact with directly. The RouteControllerDelegate
protocol allows your application to react to location-related events as they occur. Corresponding Notification
s are also posted to the shared NotificationCenter
. These notifications indicate the current state of the application in the form of a RouteProgress
object.
For further details, consult the guides and examples included with this API reference. If you have any questions, please see our help page. We welcome your bug reports, feature requests, and contributions.
Changes in version 0.17.0
- New guidance navigation styles are provided through
MGLStyle
. (#1366)
Packaging
- Upgraded to the Mapbox Maps SDK for iOS v4.0.0. If you have customized the route map’s appearance, you may need to migrate your code to use expressions instead of style functions. (#1076)
- Added a Korean localization. (#1346)
User interface
- Exit indications are now drawn accurately with a correct exit heading. (#1288)
- Added the
NavigationViewControllerDelegate.navigationViewController(_:roadNameAt:)
method for customizing the contents of the road name label that appears towards the bottom of the map view. (#1309) - If the SDK tries but fails to reroute the user, the “Rerouting…” status view no longer stays visible permanently. (#1357)
- Completed waypoints now remain on the map but are slightly translucent. (#1364)
- Fixed an issue preventing
NavigationViewController.navigationMapView(_:simplifiedShapeDescribing:)
(nowNavigationViewController.navigationMapView(_:simplifiedShapeFor:)
) from being called. (#1413)
Spoken instructions
- Fixed an issue causing the wrong instructions to be spoken. (#1396)
User location
- The
RouteController.routeProgress
property is now available in Objective-C. (#1323) - Added a
RouteController.tunnelSimulationEnabled
option that keeps the user location indicator moving steadily while the user travels through a tunnel and GPS reception is unreliable. (#1218)
Other changes
DistanceFormatter
,ReplayLocationManager
,SimulatedLocationManager
,LanesView
, andManueverView
are now subclassable. (#1345)- Renamed many
NavigationViewController
andNavigationMapViewDelegate
methods (#1364, #1338, #1318, #1378, #1413):NavigationViewControllerDelegate.navigationViewControllerDidCancelNavigation(_:)
toNavigationViewControllerDelegate.navigationViewControllerDidDismiss(_:byCanceling:)
-[MBNavigationViewControllerDelegate navigationViewController:didArriveAt:]
to-[MBNavigationViewControllerDelegate navigationViewController:didArriveAtWaypoint:]
in Objective-CNavigationViewControllerDelegate.navigationMapView(_:routeStyleLayerWithIdentifier:source:)
toNavigationViewControllerDelegate.navigationViewController(_:routeStyleLayerWithIdentifier:source:)
NavigationViewControllerDelegate.navigationMapView(_:routeCasingStyleLayerWithIdentifier:source:)
toNavigationViewControllerDelegate.navigationViewController(_:routeCasingStyleLayerWithIdentifier:source:)
NavigationViewControllerDelegate.navigationMapView(_:shapeFor:)
toNavigationViewControllerDelegate.navigationViewController(_:shapeFor:)
NavigationViewControllerDelegate.navigationMapView(_:simplifiedShapeFor:)
toNavigationViewControllerDelegate.navigationViewController(_:simplifiedShapeFor:)
NavigationViewControllerDelegate.navigationMapView(_:waypointStyleLayerWithIdentifier:source:)
toNavigationViewControllerDelegate.navigationViewController(_:waypointStyleLayerWithIdentifier:source:)
NavigationViewControllerDelegate.navigationMapView(_:waypointSymbolStyleLayerWithIdentifier:source:)
toNavigationViewControllerDelegate.navigationViewController(_:waypointSymbolStyleLayerWithIdentifier:source:)
NavigationViewControllerDelegate.navigationMapView(_:shapeFor:legIndex:)
toNavigationViewControllerDelegate.navigationViewController(_:shapeFor:legIndex:)
NavigationViewControllerDelegate.navigationMapView(_:didTap:)
toNavigationViewControllerDelegate.navigationViewController(_:didSelect:)
NavigationViewControllerDelegate.navigationMapView(_:imageFor:)
toNavigationViewControllerDelegate.navigationViewController(_:imageFor:)
NavigationViewControllerDelegate.navigationMapView(_:viewFor:)
toNavigationViewControllerDelegate.navigationViewController(_:viewFor:)
NavigationViewControllerDelegate.navigationViewController(_:didSend:feedbackType:)
toNavigationViewControllerDelegate.navigationViewController(_:didSendFeedbackAssigned:feedbackType:)
-[MBNavigationViewControllerDelegate navigationViewController:shouldDiscard:]
to-[MBNavigationViewControllerDelegate navigationViewController:shouldDiscardLocation:]
in Objective-C-[MBNavigationViewControllerDelegate navigationViewController:roadNameAt:]
to-[MBNavigationViewControllerDelegate navigationViewController:roadNameAtLocation:]
NavigationMapViewDelegate.navigationMapView(_:shapeDescribing:)
toNavigationMapViewDelegate.navigationMapView(_:shapeFor:)
.NavigationMapViewDelegate.navigationMapView(_:simplifiedShapeDescribing:)
toNavigationMapViewDelegate.navigationMapView(_:simplifiedShapeFor:)
.-[MBNavigationMapViewDelegate navigationMapView:shapeDescribingWaypoints:legIndex:]
to-[MBNavigationMapViewDelegate navigationMapView:shapeForWaypoints:legIndex:]
in Objective-C
RouteController.recordFeedback(type:description:)
now returns aUUID
instead of a string. SomeRouteController
methods have been renamed to acceptUUID
s as arguments instead of strings. (#1413)- Renamed
TunnelIntersectionManagerDelegate.tunnelIntersectionManager(_:willEnableAnimationAt:callback:)
toTunnelIntersectionManagerDelegate.tunnelIntersectionManager(_:willEnableAnimationAt:completionHandler:)
andTunnelIntersectionManagerDelegate.tunnelIntersectionManager(_:willDisableAnimationAt:callback:)
toTunnelIntersectionManagerDelegate.tunnelIntersectionManager(_:willDisableAnimationAt:completionHandler:)
. (#1413)