Upgrading from v1.x to v2.0.x

Mapbox Navigation SDK for iOS v2.0.0 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, you will need to migrate from framework bundles to XCFrameworks.

Starting with version v2.0.0, 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.

Version 2.0.0 includes numerous 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.

Pricing

• MBXNavigationBillingMethod is no longer supported. (#3147)
• New per trip pricing option. For more information, see the “Pricing” guide (#3147)

System requirements

• Supported dependency managers:
  • Swift Package Manager (new)
  • CocoaPods
  • Carthage (MapboxCoreNavigation only; MapboxNavigation 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. Please consult the Turf v2.0.0 release notes, which details changes to the type system and examples for upgrading.

GeoJSON is now represented using Turf types throughout Mapbox’s SDKs, including in the map SDK’s public API, so it is no longer necessary to convert between Turf GeoJSON types and the map 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.

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. Please 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).

Map

Symbols renamed or replaced:

• Removed obsoleted NavigationMapView.navigationMapDelegate, which was replaced by NavigationMapView.delegate.
• Renamed NavigationMapView.navigationMapViewDelegate to NavigationMapView.delegate.
• Renamed NavigationMapViewController.mapView to NavigationMapViewController.navigationMapView.
• Removed NavigationAnnotation.
• NavigationMapView.updateCourseTracking(location:camera:animated:) accepts a CameraOptions as an argument instead of an MGLMapCamera.
• Removed NavigationMapView.showsUserLocation, because NavigationMapView no longer inherits from MGLMapView. NavigationMapView.mapView is now exposed as public property instead.
• Changed the type of NavigationViewController.pendingCamera from MGLMapCamera to CameraOptions.
• Renamed the Constants.MBRouteLineWidthByZoomLevel variable to Constants.MBRouteLineWidthByZoomLevel, which now accepts Double for keys and values.
• Renamed the MBCurrentLegAttribute property to CurrentLegAttribute.
• Renamed the MBCongestionAttribute property to CongestionAttribute.
• Renamed NavigationViewController.mapView to NavigationViewController.navigationMapView.
• Renamed NavigationMapView.highlightBuildings(at:in3D:) to NavigationMapView.highlightBuildings(at:in3D:completion:).
• 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:)

Location tracking

Symbols renamed or replaced:

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

CarPlay

Symbols renamed or replaced:

• Removed the deprecated CarPlayNavigationDelegate.carPlayNavigationViewControllerDidArrive(_:) method.
• Renamed CarPlayManager.mapView to CarPlayManager.navigationMapView.
• Removed the deprecated CarPlayManager.overviewButton property.
• Removed the unused CarPlayNavigationViewController.drivingSide property.
• Renamed CarPlayNavigationDelegate to CarPlayNavigationViewControllerDelegate and CarPlayNavigationViewController.carPlayNavigationDelegate to CarPlayNavigationViewController.delegate.
• Moved CarPlaySearchController.searchTemplate(_:updatedSearchText:completionHandler:), CarPlaySearchController.searchTemplate(_:searchTemplate:selectedResult:completionHandler:) methods to CarPlaySearchControllerDelegate protocol; Renamed resultsOrNoResults(_:limit:) to searchResults(with:limit:).
• Moved GeocodedPlacemark extension from CarPlaySearchController to the application level. Removed GeocodedPlacemark.listItem().
• CarPlayManagerDelegate.carplayManagerShouldDisableIdleTimer(_:) was renamed to CarPlayManagerDelegate.carPlayManagerShouldDisableIdleTimer(_:).

Other changes

Symbols renamed or replaced:

• Removed the deprecated InstructionsBannerViewDelegate.didDragInstructionsBanner(_:) method.
• Removed the unused NavigationViewController.origin property.
• NavigationViewController.indexedRoute, NavigationService.indexedRoute and Router.indexedRoute properties are readonly now. Use dedicated Router.updateRoute(with:routeOptions:) method to update the route.
• Removed the NavigationViewController.indexedRoute, NavigationService.indexedRoute, Router.indexedRoute properties in favor of NavigationViewController.indexedRouteResponse, NavigationService.indexedRouteResponse, and Router.indexedRouteResponse. Removed the RouteProgress.indexedRoute property. Added NavigationViewController.prepareViewLoading(routeResponse:, routeIndex:, routeOptions:, navigationOptions:) method to setup it for UIStoryboard.
• Renamed RouteOptions.without(waypoint:) to RouteOptions.without(_:).
• Renamed FeedbackType to ActiveNavigationFeedbackType and EventsManagerDataSource to ActiveNavigationEventsManagerDataSource.

Tiles cache cleanup:

When migrating please ensure you have cleaned up old navigation tiles cache folder to reclaim disk space.

• Navigation SDK 2.0 caches navigation tiles in a default folder under <APP_FOLDER>/Library/Caches/<APP_BUNDLE_ID>/tiles.
• Previous versions of Nav SDK used to cache tiles under a default folder <APP_FOLDER>/Library/Caches/<APP_BUNDLE_ID>/.mapbox.
• Old cache is not compatible with a new version of SDK 2.0.
• It makes sense to delete any folders used previously for caching including a default one.
  • NavigationSettings.shared.tileStoreConfiguration enables you to specify a path where nav and map tiles will be saved and if a custom directory was used, it should be cleared as well.
  • Be sure to configure the custom path before starting a free drive or an active guidance session if you don't want the defaults.

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

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.