Mapbox Navigation SDK for iOS

Mapbox Navigation SDK

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 Swift Package Manager

To install the MapboxNavigation framework in an application using Swift Package Manager:

  1. 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.

  2. In Xcode, go to File ‣ Swift Packages ‣ Add Package Dependency.

  3. Enter https://github.com/mapbox/mapbox-navigation-ios.git as the package repository and click Next.

  4. Set Rules to Version, Up to Next Major, and enter ${SHORT_VERSION} as the minimum version requirement. Click Next.

To install the MapboxCoreNavigation framework in another package rather than an application, run swift package init to create a Package.swift, then add the following dependency:

// Latest prerelease
.package(name: "MapboxNavigation", url: "https://github.com/mapbox/mapbox-navigation-ios.git", from: "${SHORT_VERSION}")

Using CocoaPods

To install the MapboxNavigation framework using CocoaPods:

  1. 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.

  2. Create a Podfile with the following specification:

    # Latest stable release
    pod 'MapboxNavigation', '~> 2.0'
    # Latest prerelease
    pod 'MapboxCoreNavigation', :git => 'https://github.com/mapbox/mapbox-navigation-ios.git', :tag => 'v${SHORT_VERSION}'
    pod 'MapboxNavigation', :git => 'https://github.com/mapbox/mapbox-navigation-ios.git', :tag => 'v${SHORT_VERSION}'
    
  3. Run pod repo update && pod install and open the resulting Xcode workspace.

Configuration

  1. 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.

  2. 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.

  3. 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 and location values to the UIBackgroundModes 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 Notifications 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-beta.21. (#3039)
  • MapboxNavigation now depends on MapboxNavigationNative v52.0.0. (#3039)
  • MapboxNavigation now depends on MapboxCommon v13.0.0. (#3039)
  • MapboxNavigation now depends on MapboxMobileEvents v1.0.2. (#3039)
  • MapboxCoreNavigation depends on MapboxDirections v2.0.0-beta.3 but no longer depends on MapboxAccounts. (#2808, #2829, #2837)
  • 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.
  • Carthage v0.38 or above is now required for installing this SDK if you use Carthage. (#3031)
  • You can fully build this SDK on Macs with Apple Silicon. (#3031)

Map

Location tracking

Electronic horizon

Camera

  • Added Navigation Viewport Camera APIs, which allow to control camera viewport system frames based on various properties, such as: current location, some or all of the remaining route line coordinates, upcoming maneuvers etc. This allows to provide a camera viewport system, which is optimal for visualization and animation in navigation applications. (#2826)
  • Removed CarPlayNavigationViewController.tracksUserCourse, NavigationMapView.defaultAltitude, NavigationMapView.zoomedOutMotorwayAltitude, NavigationMapView.longManeuverDistance, NavigationMapView.showsUserLocation, NavigationMapView.tracksUserCourse, NavigationMapView.enableFrameByFrameCourseViewTracking(for:), NavigationMapView.updateCourseTracking(location:camera:animated:) NavigationMapView.defaultPadding, NavigationMapView.setOverheadCameraView(from:along:for:), NavigationMapView.recenterMap(), NavigationMapViewDelegate.navigationMapViewUserAnchorPoint(_:), NavigationMapViewCourseTrackingDelegate, NavigationViewController.pendingCamera in favor of new Navigation Viewport Camera APIs. (#2826)
  • Replaced CourseUpdatable.update(location:pitch:direction:animated:tracksUserCourse:) with CourseUpdatable.update(location:pitch:direction:animated:navigationCameraState:) to provide more agile way of handling NavigationCameraState. (#2826)
  • Added NavigationMapView.init(frame:navigationCameraType:) to be able to provide type of NavigationCamera, which should be used for that specific instance of NavigationMapView (either iOS or CarPlay). (#2826)
  • Added NavigationCamera, ViewportDataSourceType, ViewportDataSourceDelegate, NavigationCameraState Navigation Viewport Camera APIs. By default Navigation SDK for iOS provides default camera behavior via NavigationViewportDataSource and NavigationCameraStateTransition classes. If you’d like to override current behavior use ViewportDataSource and CameraStateTransition protocols for custom behavior. (#2826)
  • Added NavigationViewportDataSourceOptions, which provides the ability to change specific CameraOptions of NavigationViewportDataSource. (#2944)

CarPlay

Other changes

  • Removed deprecated InstructionsBannerViewDelegate.didDragInstructionsBanner(_:) method. (#2808)
  • Removed NavigationViewController.origin property, which was not used. (#2808)
  • A new predictive cache proactively fetches tiles which may become necessary if the device loses its Internet connection at some point during passive or active turn-by-turn navigation. Pass a PredictiveCacheOptions instance into the NavigationOptions(styles:navigationService:voiceController:topBanner:bottomBanner:predictiveCacheOptions:) initializer as you configure a NavigationViewController, or manually call NavigationMapView.enablePredictiveCaching(options:). (#2830)
  • Added the Directions.calculateOffline(options:completionHandler:) and Directions.calculateWithCache(options:completionHandler:) methods, which incorporate routing tiles from the predictive cache when possible to avoid relying on a network connection to calculate the route. RouteController now also uses the predictive cache when rerouting. (#2848)
  • Fixed an issue where PassiveLocationDataSource and RouteController did not use the access token and host specified by PassiveLocationDataSource.directions and RouteController.directions, respectively. Added the PredictiveCacheOptions.credentials property for specifying the access token and host used for prefetching resources. (#2876)
  • The top banner can now show a wider variety of turn lane configurations, such as combination U-turn/left turn lanes and combination through/slight right turn lanes. (#2882)
  • Exposed NavigationMapView.mapTileStore, PassiveLocationDataSource.navigatorTileStore and RouteController.navigatorTileStore for accessing corresponding TileStore instancies (#2955)
  • Fixed an issue that the current road name label flashes when camera state changes or travels onto an unnamed road. (#2958)
  • Added the NavigationOptions.tileStoreConfiguration property and arguments to PassiveLocationDataSource(directions:systemLocationManager:tileStoreLocation:), NavigationMapView(frame:navigationCameraType:tileStoreLocation:), and PredictiveCacheManager(predictiveCacheOptions:tileStoreMapOptions:) for customizing the locations where navigation and map tiles are stored. (#2956)
  • Fixed an issue where lane guidance icons would sometimes highlight the wrong arrow.(#2942)
  • The duration annotations added by the NavigationMapView.showRouteDurations(along:) method are now set in the fonts you specify using the NavigationMapView.routeDurationAnnotationFontNames property. Use this property to specify a list of fallback fonts for better language support. (#2873)
  • Removed deprecated and obsoleted EventsManager typealias, StatusView.delegate, StatusView.canChangeValue, RouteLegProgress.upComingStep, StatusViewDelegate, DeprecatedStatusViewDelegate and BottomBannerViewController.init(delegate:). (#2993)
  • Fixed a potential memory leak when using MultiplexedSpeechSynthesizer. (#3005)
  • Fixed an issue where instruction banners could appear in the wrong color after switching between Styles. (#2977)
  • Developers can create an instance of NavigationViewController from UIStoryboardSegue, which is located in Navigation.storyboard. To successfully create NavigationViewController instance developer has to pre-define route, routeIndex, routeOptions and navigationOptions properties of NavigationViewController in UIViewController.prepare(for:sender:). (#2974)
  • Added methods for convenience checking Navigation tiles in a TileStore: containsLatestNavigationTiles(forCacheLocation:, completion:), tileRegionContainsLatestNavigationTiles(forId:, cacheLocation:, completion:) and methods for getting Navigation tiles from TilesetDescriptorFactory: getLatest(forCacheLocation:), getSpecificVersion(forCacheLocation:, version:). (#3015)
  • Fixed a thread-safety issue in UnimplementedLogging protocol implementation. (#3024)
  • Implemented automatic switching to older navigation tiles versions (if they are present in current TileStore) and back. You can subscribe to Notification.Name.navigationDidSwitchToFallbackVersion and Notification.Name.navigationDidSwitchToTargetVersion notifications to monitor such events. (#3014)
  • Fixed an issue where the current road name label sometimes displayed the name of an intersecting road instead of the current road or blinked in and out. (#3019)
  • Fixed an issue where 'Navigation cancel’ event might be not logged. (#3050)
  • Fixed an issue where offline route calculation might hang up. (#3040)
  • Fixed the moment of custom feedback event creation. (#3049)
  • Fixed a bug in RouterDelegate.router(_:shouldDiscard:) handling. If you implemented this method, you will need to reverse the value you return. Previously, if you returned true, the Router wouldn’t discard the location. (#3058)
  • Changed default navigation history storage location to user’s application support directory. (#3039)