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 5 in Xcode 10.2. The Mapbox Navigation and Mapbox Core Navigation frameworks run on iOS 10.0 and above.
Installation
Using CocoaPods
To install Mapbox Navigation using CocoaPods:
Go to your Mapbox account dashboard and create an access token that has the
DOWNLOADS:READ
scope. PLEASE NOTE: This is not the same as your production Mapbox API token. Make sure to keep it private and do not insert it into any Info.plist file. Create a file named.netrc
in your home directory if it doesn’t already exist, then add the following lines to the end of the file:machine api.mapbox.com login mapbox password PRIVATE_MAPBOX_API_TOKEN
where PRIVATE_MAPBOX_API_TOKEN is your Mapbox API token with the
DOWNLOADS:READ
scope.Create a Podfile with the following specification:
pod 'MapboxNavigation', '~> 2.0'
Run
pod repo update && pod install
and open the resulting Xcode workspace.
Using Carthage
Alternatively, to install Mapbox Navigation using Carthage:
Go to your Mapbox account dashboard and create an access token that has the
DOWNLOADS:READ
scope. PLEASE NOTE: This is not the same as your production Mapbox API token. Make sure to keep it private and do not insert it into any Info.plist file. Create a file named.netrc
in your home directory if it doesn’t already exist, then add the following lines to the end of the file:machine api.mapbox.com login mapbox password PRIVATE_MAPBOX_API_TOKEN
where PRIVATE_MAPBOX_API_TOKEN is your Mapbox API token with the
DOWNLOADS:READ
scope.(Optional) Clear your Carthage caches:
rm -rf ~/Library/Caches/carthage/ ~/Library/Caches/org.carthage.CarthageKit/binaries/{MapboxAccounts,MapboxCommon-ios,MapboxNavigationNative,mapbox-ios-sdk-dynamic}
Create a Cartfile with the following dependency:
github "mapbox/mapbox-navigation-ios" ~> 2.0
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. Usage of Mapbox APIs is billed together based on monthly active users (MAU) rather than individually by HTTP request.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 the map.
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 Signing & 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
// Define two waypoints to travel between
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")
// Set options
let routeOptions = NavigationRouteOptions(waypoints: [origin, destination])
// Request a route using MapboxDirections
Directions.shared.calculate(routeOptions) { [weak self] (session, result) in
switch result {
case .failure(let error):
print(error.localizedDescription)
case .success(let response):
guard let route = response.routes?.first, let strongSelf = self else {
return
}
// Pass the generated route to the the NavigationViewController
let viewController = NavigationViewController(for: route, routeIndex: 0, routeOptions: routeOptions)
viewController.modalPresentationStyle = .fullScreen
strongSelf.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. PassiveLocationManager
is an optional alternative to CLLocationManager
for use with any standalone MapView
or NavigationMapView
.
CarPlayManager
is the class that manages the CarPlay screen if your application is CarPlay-enabled. It provides a main map for browsing, a search interface powered by MapboxGeocoder.swift, and a turn-by-turn navigation UI similar to the one provided by NavigationViewController
. Your UIApplicationDelegate
subclass can conform to the CarPlayManagerDelegate
protocol to manage handoffs between NavigationViewController
and the CarPlay device, as well as to customize some aspects of the CarPlay navigation experience. To take advantage of CarPlay functionality, your application must have a CarPlay navigation application entitlement and be built in Xcode 10 or above, and the user’s iPhone or iPad must have iOS 12 or above installed.
Core Navigation
MapboxNavigationService
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 NavigationServiceDelegate
protocol allows your application to react to location-related events as they occur. Corresponding Notification
s from the NavigationService
‘s RouteController
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 2.0.0
Packaging
- The Mapbox Navigation SDK for iOS license has changed from the ISC License to the Mapbox Terms of Service. (#2808)
- You can now install MapboxNavigation using Swift Package Manager, but you can no longer install it using Carthage. If you previously installed MapboxNavigation using Carthage, use Swift Package Manager instead. (#2808)
- MapboxNavigation now depends on MapboxMaps v10.0.0, MapboxNavigationNative v42.0.1, and MapboxDirections v2.0.0-alpha.1. (#2808)
- MapboxNavigation and MapboxCoreNavigation require iOS 11.0 or above to run. iOS 10.x is no longer supported. (#2808)
- Xcode 12.4 or above is now required for building this SDK from source.
Map
MBXAccessToken
is now required forMapboxMaps
, and must be set in the Info.plist file. (#2808)- Removed obsoleted
NavigationMapView.navigationMapDelegate
, which was replaced byNavigationMapView.delegate
. (#2808) NavigationMapView.navigationMapViewDelegate
was renamed toNavigationMapView.delegate
. (#2808)NavigationMapViewController.mapView
was renamed toNavigationMapViewController.navigationMapView
. (#2808)- Removed
NavigationAnnotation
. (#2808) NavigationMapView.updateCourseTracking(location:camera:animated:)
no longer acceptsMGLMapCamera
as parameter, and usesCameraOptions
instead. (#2808)NavigationMapView.showsUserLocation
was removed, becauseNavigationMapView
is no longer inherited fromMGLMapView
.NavigationMapView.mapView
is now exposed as public property instead. (#2808)NavigationViewController.pendingCamera
type was changed fromMGLMapCamera
toCameraOptions
. (#2808)- Renamed public constant
Constants.MBRouteLineWidthByZoomLevel
to public variableConstants.MBRouteLineWidthByZoomLevel
, which now acceptsDouble
for keys and values. (#2808) - Renamed public property
MBCurrentLegAttribute
toCurrentLegAttribute
. (#2808) - Renamed public property
MBCongestionAttribute
toCongestionAttribute
. (#2808) NavigationViewController.mapView
was renamed toNavigationViewController.navigationMapView
. (#2808)
Location tracking
PassiveLocationManager
now conforms toLocationProvider
protocol instead ofMGLLocationManager
. (#2808)- Type of
PassiveLocationManager.delegate
property was changed fromMGLLocationManagerDelegate
toLocationProviderDelegate
. (#2808) PassiveLocationManager.accuracyAuthorization()
was replaced withPassiveLocationManager.accuracyAuthorization
property, which now returnsCLAccuracyAuthorization
instead ofMBNavigationAccuracyAuthorization
. (#2808)- Fixed a potential hang when
PassiveLocationDataSource
fails to download routing tiles. (#2808) - Fixed an issue where
RouteController
orPassiveLocationDataSource
sometimes snapped the user’s location assuming a path that violated a turn restriction. (#2808) - Improved performance and decreased memory usage when downloading routing tiles. (#2808)
CarPlay
- Removed deprecated
CarPlayNavigationDelegate.carPlayNavigationViewControllerDidArrive(_:)
. (#2808) CarPlayManager.mapView
was renamed toCarPlayManager.navigationMapView
. (#2808)- Removed deprecated
CarPlayManager.overviewButton
. (#2808) - Removed unused
CarPlayNavigationViewController.drivingSide
property. (#2808)