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 for the MapboxCoreNavigation framework, you will need to migrate from framework bundles to XCFrameworks.

Starting with version v2.0.0, you can choose from two new pricing options depending on your use case: per-trip 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.

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.

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. 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.
• 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. 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).
• The MBXNavigationBillingMethod Info.plist key is no longer supported.

Map

Symbols 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:).

Camera

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

User location indicator

Symbols 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

Symbols 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

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

Location tracking

Symbols 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(_:completionHandler:). These methods are now asynchronous, and their completion handlers indicate 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.

Passive navigation

Symbols 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() was replaced 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().

CarPlay

Symbols 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(_:).

User feedback

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

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

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, please contact Mapbox’s support team.