Skip to main content

Migrate to v2

Additional Developer Resources

Mapbox Navigation SDK for iOS v2 is a major new version of the SDK. To upgrade, follow the installation instructions. Note that the MapboxNavigation framework’s Carthage support has been discontinued in favor of Swift Package Manager. If you decide to keep using Carthage for the MapboxCoreNavigation framework, you will need to migrate from framework bundles to XCFrameworks.

Starting with v2.0.0, you can choose from two new pricing options depending on your use case: metered or unlimited trips. Also, the Mapbox Navigation SDK is licensed under the Mapbox Terms of Service, a proprietary license. It is no longer available under the permissive ISC License.

Navigation SDK v2 includes many important changes to the public APIs of the MapboxNavigation and MapboxCoreNavigation frameworks as well as their dependencies. There are several backwards-incompatible changes to be aware of as you upgrade, which are discussed below and divided by framework so that you can upgrade different portions of your application at different times.

System requirements​

  • Supported dependency managers:
    • Swift Package Manager (new)
    • CocoaPods
    • Carthage (MapboxCoreNavigation only. MapboxNavigation and mapbox-directions-swift command line tool no longer supported.)
  • Minimum Xcode version required to build the SDK: 12.4 (11.x no longer supported)
  • Minimum iOS deployment target: 11.0 (10.x no longer supported)

Upgrading Turf from v1.x to v2.0.0​

Turf v2 revamps the GeoJSON types to better conform to the GeoJSON specification. Consult the Turf v2.0.0 release notes, which detail changes to the type system and examples for upgrading.

GeoJSON is now represented using Turf types throughout Mapbox’s SDKs, including in the Maps SDK’s public API, so it is no longer necessary to convert between Turf GeoJSON types and the Maps SDK’s shape types.

Upgrading MapboxDirections from v1.x to v2.0.0​

  • The preferred way to set your Mapbox access token is to set the MBXAccessToken key in your application’s Info.plist. MGLMapboxAccessToken is still supported as a deprecated fallback.
  • The Incident.impact property is now an Incident.Impact value instead of a string.
  • RouteOptions.alleyPriority, RouteOptions.walkwayPriority, and RouteOptions.speed are now optional. Set them explicitly if you want to include them in the HTTP request. Renamed DirectionsOptions.default to DirectionsOptions.medium.
  • Removed the DirectionsResult.routeIdentifier property. Use the RouteResponse.identifier property in conjunction with an index into the RouteResponse.routes array instead.

Upgrading MapboxSpeech from v1.x to v2.0.0​

The preferred way to set your Mapbox access token is to set the MBXAccessToken key in your application’s Info.plist. MGLMapboxAccessToken is still supported as a deprecated fallback.

Upgrading from Mapbox Maps SDK v6.x to MapboxMaps v10.0.0​

Mapbox Maps SDK v10 introduces 3D terrain, improves performance, and upgrades from OpenGL to Metal. Consult the v10 migration guide, which details many changes that likely affect your application’s user interface code.

Other changes:

  • The preferred way to set your Mapbox access token is to set the MBXAccessToken key in your application’s Info.plist. MGLMapboxAccessToken is no longer supported.

Upgrading MapboxNavigation from v1.x to v2.0.0​

Packaging​

  • MapboxCoreNavigation no longer depends on MapboxAccounts.
  • MapboxNavigation now depends on MapboxMaps instead of Mapbox.framework (Mapbox-iOS-SDK pod).
  • The MBXNavigationBillingMethod Info.plist key is no longer supported.

Map​

The following symbols were renamed or replaced:

GUIDE
Maps for navigation

Read more about using maps in the Navigation SDK v2.

Camera​

The following symbols were renamed or replaced:

  • Removed the CarPlayNavigationViewController.tracksUserCourse property and the NavigationMapView.enableFrameByFrameCourseViewTracking(for:), NavigationMapView.updateCourseTracking(location:camera:animated:), NavigationMapView.setOverheadCameraView(from:along:for:), and NavigationMapView.recenterMap() methods in favor of the NavigationMapView.navigationCamera property.
  • Removed the NavigationMapView.defaultAltitude, NavigationMapView.zoomedOutMotorwayAltitude, NavigationMapView.longManeuverDistance, NavigationMapView.defaultPadding, NavigationMapView.courseTrackingDelegate, and NavigationViewController.pendingCamera properties and the NavigationMapViewDelegate.navigationMapViewUserAnchorPoint(_:) method in favor of the NavigationCamera.cameraStateTransition property.
  • NavigationMapView.updateCourseTracking(location:camera:animated:) accepts a CameraOptions instance instead of an MGLMapCamera object.
  • Changed the NavigationViewController.pendingCamera property’s type from MGLMapCamera to CameraOptions.
GUIDE
Navigation viewport camera

Read more about how the camera works in the Navigation SDK v2.

User location indicator​

The following symbols were renamed or replaced:

Route overlay​

The following symbols were renamed or replaced:

Banners and guidance instructions​

The following symbols were renamed or replaced:

  • Removed the InstructionsBannerViewDelegate.didDragInstructionsBanner(_:) method.
  • Removed the StatusView.delegate and StatusView.canChangeValue properties and the StatusViewDelegate and DeprecatedStatusViewDelegate protocols.
  • Removed the BottomBannerViewController(delegate:) initializer.
GUIDE
User interface: Maneuver instructions

Read more about how maneuver instructions work in the Navigation SDK v2.

Location tracking​

The following symbols were renamed or replaced:

GUIDE
Location tracking

Read more about how location tracking works in the Navigation SDK v2.

Passive navigation​

Passive navigation is also called free-drive navigation. The following symbols were renamed or replaced:

GUIDE
Free-drive navigation

Read more about how free-drive navigation, also referred to as passive navigation, works in the Navigation SDK v2.

CarPlay​

The following symbols were renamed or replaced:

GUIDE
CarPlay

Read more about how CarPlay integration works in the Navigation SDK v2.

User feedback​

The following symbols were renamed or replaced:

GUIDE
Feedback

Read more about how user feedback works in the Navigation SDK v2.

Other migration steps​

Configuring storyboards​

If your storyboard has a segue to NavigationViewController in Navigation.storyboard, you have to call the NavigationViewController.prepareViewLoading(routeResponse:routeIndex:routeOptions:navigationOptions:) method in your implementation of the UIViewController.prepare(for:sender:) method.

Tile cache cleanup​

When migrating make sure you have cleaned up the old navigation tiles cache folder to reclaim disk space:

  • Navigation SDK v2 caches navigation tiles in a default folder under <APP_FOLDER>/Library/Caches/<APP_BUNDLE_ID>/tiles.
  • Previous versions of Navigation SDK cache tiles in a default folder under <APP_FOLDER>/Library/Caches/<APP_BUNDLE_ID>/.mapbox.
  • Caches from previous versions of the Navigation SDK are not compatible with v2.
  • Delete any folders used for caching with previous versions of the SDK including a default one.
    • NavigationSettings.shared.tileStoreConfiguration enables you to specify a path where navigation and map tiles will be saved. If a custom directory was used, you should remove it, too.
    • Be sure to configure the custom path before starting a free drive or an active guidance session if you don't want to use the default location.

Migrating a project from framework bundles to XCFrameworks​

Switching from discrete framework bundles to XCFrameworks requires a few changes to your project. Follow these migration steps to switch:

  1. Delete your Carthage folder to remove any existing framework bundles.
  2. Build new XCFrameworks by running carthage bootstrap --platform iOS --use-xcframeworks --use-netrc.
  3. Remove references to the old frameworks in each of your targets:
    • Delete references to Carthage frameworks from the target's Frameworks, Libraries, and Embedded Content section and/or its Link Binary with Libraries build phase.
    • Delete references to Carthage frameworks from any Copy Files build phases.
    • Delete the target's carthage copy-frameworks build phase, if present.
  4. Add references to XCFrameworks in each of your targets:
    • For an application target: In the General settings tab, in the Frameworks, Libraries, and Embedded Content section, drag and drop each XCFramework you use from the Carthage/Build folder on disk.
    • For a framework target: In the Build Phases tab, in a Link Binary with Libraries phase, drag and drop each XCFramework you use from the Carthage/Build folder on disk.

Need help?​

If you have any questions, contact Mapbox’s support team.

Additional Developer Resources
Was this page helpful?