Migrate to v2

Join the Mapbox Developers Discord Communityarrow-right

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:

• Replaced the NavigationMapView.navigationMapDelegate and NavigationMapView.navigationMapViewDelegate properties with a single NavigationMapView.delegate property.
• Renamed the NavigationViewController.mapView property to NavigationViewController.navigationMapView.
• Renamed the MGLStyle.navigationDayStyleURL and MGLStyle.navigationNightStyleURL properties to StyleURI.navigationDay and StyleURI.navigationNight, respectively. Removed the MGLStyle.navigationDayStyleURL(version:) and MGLStyle.navigationNightStyleURL(version:) methods in favor of these renamed properties.
• Renamed the NavigationMapView.highlightBuildings(at:in3D:) method to NavigationMapView.highlightBuildings(at:in3D:completion:).

guide

Maps for navigation

Read more about using maps in the Navigation SDK v2.

chevron-right

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.

chevron-right

User location indicator

The following symbols were renamed or replaced:

• Removed the NavigationMapView.showsUserLocation and NavigationMapView.tracksUserCourse properties in favor of NavigationMapView.userLocationStyle.
• Removed the NavigationMapView.userCourseView property in favor of the associated value when NavigationMapView.userLocationStyle is set to UserLocationStyle.courseView(_:).
• Renamed the CourseUpdatable.update(location:pitch:direction:animated:tracksUserCourse:) method to CourseUpdatable.update(location:pitch:direction:animated:navigationCameraState:).

Route overlay

The following symbols were renamed or replaced:

• Removed the NavigationAnnotation class.
• Renamed the MBRouteLineWidthByZoomLevel property to Constants.RouteLineWidthByZoomLevel and changed its type to Double for keys and values.
• Renamed the MBCurrentLegAttribute and MBCongestionAttribute constants to Constants.CurrentLegAttribute and Constants.CongestionAttribute, respectively.
• Renamed the NavigationMapView.updateRoute(_:) method to NavigationMapView.travelAlongRouteLine(to:).
• Renamed the following waypoint styling delegate methods:
  • NavigationMapViewDelegate.navigationMapView(_:waypointCircleLayerWithIdentifier:source:) to NavigationMapViewDelegate.navigationMapView(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)
  • NavigationMapViewDelegate.navigationMapView(_:waypointSymbolLayerWithIdentifier:source:) to NavigationMapViewDelegate.navigationMapView(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)
  • NavigationViewControllerDelegate.navigationViewController(_:waypointCircleLayerWithIdentifier:source:) to NavigationViewControllerDelegate.navigationViewController(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)
  • NavigationViewControllerDelegate.navigationViewController(_:waypointSymbolLayerWithIdentifier:source:) to NavigationViewControllerDelegate.navigationViewController(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)
• Removed the NavigationViewController.origin property.

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.

chevron-right

Location tracking

The following symbols were renamed or replaced:

• Renamed the RouterDataSource.locationProvider and EventsManagerDataSource.locationProvider properties to RouterDataSource.locationManagerType and ActiveNavigationEventsManagerDataSource.locationManagerType, respectively.
• Renamed the Router.advanceLegIndex() method to Router.advanceLegIndex(completionHandler:) and the PassiveLocationDataSource.updateLocation(_:) method to PassiveLocationManager.updateLocation(_:completion:). These methods are now asynchronous, and their completion handlers tell you whether the operation succeeded.
• Removed the RouteLegProgress.upComingStep property.
• Removed the NavigationViewController.indexedRoute, NavigationService.indexedRoute, and Router.indexedRoute properties in favor of NavigationViewController.indexedRouteResponse, NavigationService.indexedRouteResponse, and Router.indexedRouteResponse, respectively. These properties are no longer writable; use the Router.updateRoute(with:routeOptions:completion:) method to manually reroute the user.
• Removed the RouteProgress.indexedRoute property.
• The NavigationService.router and MapboxNavigationService.router properties are no longer unsafe-unowned.
• Renamed the Router.updateRoute(with:routeOptions:) method to Router.updateRoute(with:routeOptions:completion:). The method is now asynchronous, with a new completion handler that is called when the update has completed.
• RouteOptions no longer conforms to NSCopying. Use JSONEncoder and JSONDecoder to get a copy of the RouteOptions object round-tripped through JSON.
• Renamed RouteOptions.without(waypoint:) to RouteOptions.without(_:).
• Removed Bundle.ensureSuggestedTileURLExists(), Bundle.suggestedTileURL and Bundle.suggestedTileURL(version:).
• Removed the Alert enumeration and the RouteAlert.alert, RouteAlert.distance, RouteAlert.length, RouteAlert.beginCoordinate, RouteAlert.endCoordinate, RouteAlert.beginSegmentIndex, and RouteAlert.endSegmentIndex properties in favor of a consolidated RouteAlerts.roadObject property.

guide

Location tracking

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

chevron-right

Passive navigation

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

• Renamed PassiveLocationManager to PassiveLocationProvider and PassiveLocationDataSource to PassiveLocationManager for consistency with NavigationLocationProvider and NavigationLocationManager.
• PassiveLocationProvider now conforms to the LocationProvider protocol instead of MGLLocationManager.
• The PassiveLocationProvider.delegate property is now of type LocationProviderDelegate instead of MGLLocationManagerDelegate.
• Replaced PassiveLocationManager.accuracyAuthorization() with the PassiveLocationProvider.accuracyAuthorization property, which now returns CLAccuracyAuthorization instead of MBNavigationAccuracyAuthorization.
• Renamed PassiveLocationManager.startUpdatingLocation(completionHandler:) to PassiveLocationProvider.startUpdatingLocation(). This method now runs synchronously like CLLocationManager.startUpdatingLocation().

guide

Free-drive navigation

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

chevron-right

CarPlay

The following symbols were renamed or replaced:

• Removed the CarPlayNavigationDelegate.carPlayNavigationViewControllerDidArrive(_:) method.
• Renamed the CarPlayManager.mapView property to CarPlayManager.navigationMapView.
• Removed the CarPlayManager.overviewButton property.
• Removed the CarPlayNavigationViewController.drivingSide property.
• Renamed the CarPlayNavigationDelegate protocol to CarPlayNavigationViewControllerDelegate and the CarPlayNavigationViewController.carPlayNavigationDelegate property to CarPlayNavigationViewController.delegate.
• The CarPlayNavigationViewController.styleManager and CarPlayMapViewController.styleManager properties are now read-only.
• Moved the CarPlaySearchController.searchTemplate(_:updatedSearchText:completionHandler:), CarPlaySearchController.searchTemplate(_:searchTemplate:selectedResult:completionHandler:) methods to the CarPlaySearchControllerDelegate protocol. Renamed the CarPlaySearchControllerDelegate.resultsOrNoResults(_:limit:) method to CarPlaySearchControllerDelegate.searchResults(with:limit:).
• Renamed the CarPlayManagerDelegate.carPlayManager(_:navigationServiceAlong:routeIndex:routeOptions:desiredSimulationMode:) method to CarPlayManagerDelegate.carPlayManager(_:navigationServiceFor:routeIndex:routeOptions:desiredSimulationMode:). It now returns an optional NavigationService; if it is nil, a MapboxNavigationService will be used by default.
• Renamed the CarPlayManagerDelegate.carplayManagerShouldDisableIdleTimer(_:) method to CarPlayManagerDelegate.carPlayManagerShouldDisableIdleTimer(_:).

guide

CarPlay

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

chevron-right

User feedback

The following symbols were renamed or replaced:

• The ActiveNavigationEventsManagerDataSource.router, NavigationService.eventsManager, and MapboxNavigationService.eventsManager properties are no longer unsafe-unowned.
• Removed the EventsManager type alias.
• Renamed the FeedbackViewController(eventsManager:) initializer to FeedbackViewController(eventsManager:type:). You can now customize the view controller to show only the feedback types specific to passive navigation.
• Renamed the FeedbackType enumeration to ActiveNavigationFeedbackType and the EventsManagerDataSource protocol to ActiveNavigationEventsManagerDataSource.

guide

Feedback

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

chevron-right

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.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?