> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/navigation/llms.txt) # Migrate Core Mapbox Navigation SDK v3 for iOS is a new generation of the core functionality available in Navigation SDK v2. To install the latest version of the SDK, follow [the installation instructions](https://docs.mapbox.com/ios/navigation/guides/install) and use this guide to update your application from v2 to v3. Note that the API of Mapbox Navigation SDK v3 is not stable yet, the guide describes migration to the latest version and will be updated in case of API changes. ## Requirements and dependencies changes The Navigation SDK v3 for iOS is compatible with applications that: - Are built using Swift 5.9 or higher. - Are built using Xcode 15.0 or higher. The MapboxNavigationCore framework works on iOS 14.0 and above. ### Maps SDK The Navigation SDK v3 uses the Mapbox Maps SDK v11, as opposed to Maps SDK v10 in the Navigation SDK v2. Maps SDK v11 offers the new Mapbox Standard and Standard Satellite style support, new 3D features, improved performance and a lot more. Maps SDK v11 is a **[SEMVER major](https://semver.org/) release with breaking API changes.** If the application you are migrating uses a map, make sure you read the [Maps SDK migration guide](https://docs.mapbox.com/ios/maps/guides/migrate-to-v11/) before reading the navigation-specific content below. > **Related content (guide): [Migrate to v11](https://docs.mapbox.com/ios/maps/guides/migrate-to-v11/)** > > Upgrade your application from the Mapbox Maps SDK for iOS v10 to v11. # Major changes in the Navigation SDK v3 since Navigation SDK v2 ## SDK Configuration [`NavigationSettings`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationSettings.html) is no longer available and is replaced with [`CoreConfig`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/coreconfig/) structure which consolidates all SDK configurations. It is now mandatory to provide this setting on SDK initialization. [`CoreConfig`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/coreconfig/) can be also updated at runtime, but it is not recommended as different parts of settings may be applied asynchronously and independently from each other, resulting in undesired behavior and/or UI appearance. [`CoreConfig`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/coreconfig/) contains some sub-structures which are designed to control dedicated use-cases. ## MapboxNavigation [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) is the main facade of the SDK. Comparing to v2 SDK it supersedes the [`NavigationService`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationService.html) and [`Router`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/Router.html). It handles the `Navigator`, provides control over it as well as reporting navigation events. Your typical interaction with the SDK starts like this: ```swift let coreConfig = CoreConfig(/* ... */) // your configuration let mapboxNavigationProvider = MapboxNavigationProvider(coreConfig: coreConfig) let mapboxNavigation = mapboxNavigationProvider.mapboxNavigation ``` ### Lifecycle [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) reference (or its [`MapboxNavigationProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigationprovider/)) must be maintained by the user for as long as any of SDK functionality is needed. It is acceptable to re-instantiate it but not recommended, as it is an expensive action. Multiple instances of [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) are not allowed and having that is considered a programmer error. The SDK will flag an error whenever it detects such a case. ### `NavigationService` & `Router` replacement [`NavigationService`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationService.html), [`Router`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/Router.html) and [`PassiveLocationManager`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/PassiveLocationManager.html) were the main sources of control over the SDK behavior and usage. These were used to start and stop Free Drive and Active Guidance, apply routes, switch legs and handle the outputs. It is now moved to [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/)s sub-interfaces, which are divided by use-cases. Each component has corresponding methods to trigger related actions. SDK v2 reported events via delegates ([`RouterDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html), [`NavigationServiceDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html)) and some `NotificationCenter` notifications. These are no longer available and are replaced with `Combine` publishers, which are divided by it's purpose and are available as components of [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) object. Next is the list of available [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) components: #### [`routingProvider()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/routingprovider()/) Used to do route requests. It's functionality is equivalent to v2 [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RoutingProvider.html). It does not publish any events. #### [`tripSession()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/tripsession()/) This controller is used to do a high-level operation on the navigator like entering Free Drive or Active Guidance modes. Available events publishers: - [`session`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/sessioncontroller/session/) Reports currently active navigation session state. This has no analogs in SDK v2. - [`navigationRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/sessioncontroller/navigationroutes/) Reports current [`NavigationRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationroutes/) set to the navigation. Can be used to replace [`Router.route`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/Router.html#/s:20MapboxCoreNavigation6RouterP5route0A10Directions5RouteCvp), [`NavigationService.route`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationService.html#/s:20MapboxCoreNavigation0C7ServiceP5route0A10Directions5RouteCvp) or [`NavigationService.indexedRouteResponse`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationService.html#/s:20MapboxCoreNavigation0C7ServiceP20indexedRouteResponseAA07IndexedfG0Vvp) updates. #### [`electronicHorizon()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/electronichorizon()/) This controller to toggle Electronic Horizon, and handle it's related road data. Available events publishers: - [`eHorizonEvents`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/electronichorizoncontroller/ehorizonevents/) Reports similar events to [`electronicHorizonDidUpdatePosition`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Extensions/Notification/Name.html#/s:So18NSNotificationNamea20MapboxCoreNavigationE34electronicHorizonDidUpdatePositionABvpZ), [`electronicHorizonDidEnterRoadObject`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Extensions/Notification/Name.html#/s:So18NSNotificationNamea20MapboxCoreNavigationE35electronicHorizonDidEnterRoadObjectABvpZ), [`electronicHorizonDidExitRoadObject`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Extensions/Notification/Name.html#/s:So18NSNotificationNamea20MapboxCoreNavigationE34electronicHorizonDidExitRoadObjectABvpZ) and [`electronicHorizonDidPassRoadObject`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Extensions/Notification/Name.html#/s:So18NSNotificationNamea20MapboxCoreNavigationE34electronicHorizonDidPassRoadObjectABvpZ) notifications. #### [`navigation()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/navigation()/) This controller focuses on Active Guidance mode, providing detailed control over related features and data. Available events publishers: - [`heading`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/heading/) Reports user heading updates. Replaces [`Router.heading`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/Router.html#/s:20MapboxCoreNavigation6RouterP7headingSo9CLHeadingCSgvp) property. - [`locationMatching`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/locationmatching/) Reports user location updates. Can be used to replace [`Router`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/Router.html)'s and [`PassiveLocationManager`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/PassiveLocationManager.html)'s `rawLocation` and `location` properties. - [`routeProgress`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/routeprogress/) Reports user progress along the route. Only available during the Active Guidance session. Replaces [`RouterDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html)s and [`NavigationServiceDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html)s `RouteProgress` update methods. - [`offlineFallbacks`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/offlinefallbacks/) Reports when navigator did switch tiles versions. Replaces `navigationDidSwitchToFallbackVersion` and `navigationDidSwitchToTargetVersion` notifications. - [`voiceInstructions`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/voiceinstructions/) Equivalent to [`RouterDelegate.router(_:,didPassSpokenInstructionPoint:,routeProgress:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html#/s:20MapboxCoreNavigation14RouterDelegateP6router_29didPassSpokenInstructionPoint13routeProgressyAA0D0_p_0A10Directions0iJ0CAA05RouteM0CtF) and [`NavigationServiceDelegate.navigationService(_:,didPassSpokenInstructionPoint:,routeProgress:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html#/s:20MapboxCoreNavigation0C15ServiceDelegateP010navigationD0_29didPassSpokenInstructionPoint13routeProgressyAA0cD0_p_0A10Directions0iJ0CAA05RouteM0CtF). - [`bannerInstructions`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/bannerinstructions/) Equivalent to [`RouterDelegate.router(_:,didPassVisualInstructionPoint:,routeProgress:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html#/s:20MapboxCoreNavigation14RouterDelegateP6router_29didPassVisualInstructionPoint13routeProgressyAA0D0_p_0A10Directions0iJ6BannerCAA05RouteM0CtF) and [`NavigationServiceDelegate.navigationService(_:,didPassVisualInstructionPoint:,routeProgress:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html#/s:20MapboxCoreNavigation0C15ServiceDelegateP010navigationD0_29didPassVisualInstructionPoint13routeProgressyAA0cD0_p_0A10Directions0iJ6BannerCAA05RouteM0CtF). - [`waypointsArrival`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/waypointsarrival/) Reports details about user arriving to a waypoint. Can be used to replace [`RouterDelegate.router(_:,didArriveAt:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html#/s:20MapboxCoreNavigation14RouterDelegateP6router_11didArriveAtSbAA0D0_p_0A10Directions8WaypointCtF) or [`NavigationSerivce.navigationSerivce(_:,didArriveAt:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html#/s:20MapboxCoreNavigation0C15ServiceDelegateP010navigationD0_11didArriveAtSbAA0cD0_p_0A10Directions8WaypointCtF). - [`rerouting`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/rerouting/) Reports details about the rerouting process. Replaces corresponding [`RouterDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html) and [`NavigationServiceDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html) methods. - [`continuousAlternatives`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/continuousalternatives/) Reports details about the continuous alternatives. Replaces `Router.continuousAlternatives`, corresponding [`RouterDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html) and [`NavigationServiceDelegate`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html) methods. - [`fasterRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/fasterroutes/) Reports when the navigator decides to pick similar but faster route to current destination(s). Can be used to partially replace [`RouterDelegaterouter(_:,shouldProactivelyRerouteFrom:,to:,completion:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html#/s:20MapboxCoreNavigation14RouterDelegateP6router_28shouldProactivelyRerouteFrom2to10completionyAA0D0_p_So10CLLocationC0A10Directions5RouteCyyctF) or [`NavigationServiceDelegate.navigationService(_:,shouldProactivelyRerouteFrom:,to:,completion:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html#/s:20MapboxCoreNavigation0C15ServiceDelegateP010navigationD0_28shouldProactivelyRerouteFrom2to10completionyAA0cD0_p_So10CLLocationC0A10Directions5RouteCyyctF). - [`routeRefreshing`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcontroller/routerefreshing/) Reports route refreshing. Replaces [`RouterDelegate.router(_:,didRefresh:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RouterDelegate.html#/s:20MapboxCoreNavigation14RouterDelegateP6router_10didRefreshyAA0D0_p_AA13RouteProgressCtF) or [`NavigationServiceDelegate.navigationService(_:,didRefresh:)`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/NavigationServiceDelegate.html#/s:20MapboxCoreNavigation0C15ServiceDelegateP010navigationD0_10didRefreshyAA0cD0_p_AA13RouteProgressCtF) methods. #### [`eventsManager()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/eventsmanager()/) This controller provides access to posting custom telemetry and feedback events. It does not publish any events. #### [`historyRecorder()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/historyrecorder()/) [`HistoryRecording`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/historyrecording/) allows the storing of custom events in the history log. This is handy for logging and debugging process. SDK does its own anonymous history logs collection and adding extra information to it may become increasingly useful when diagnosing an issue. This controller does not publish any events. #### [`copilot()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/copilot()/) This controller provides access to the Copilot functionality. This is an extensive logging tool, which should be explicitly enabled by the user. The controller does not publish any events. ## Requesting Routes `Directions.swift` functionality is replaced by [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/). It is equivalent to [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Protocols/RoutingProvider.html) in SDK v2, with slightly different return result. [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/) provides methods to get 'regular' Route Request as well as Map Matching Request. [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/) instance itself can be obtained from [`MapboxNavigation.routingProvider()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/routingprovider()/) method. ### Route objects Navigation SDK v2 [`IndexedRouteResponse`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Structs/IndexedRouteResponse.html) and [`RouteResponse`](https://docs.mapbox.com/ios/directions/api/2.14.4/Structs/RouteResponse.html) are replaced with single [`NavigationRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationroutes/) structure. It serves the same purpose but provides more robust control over the alternative routes and encapsulates its internal data state. Virtually every method or use case that was handling [`IndexedRouteResponse`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Structs/IndexedRouteResponse.html), now will be switched to [`NavigationRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationroutes/) usage. This includes doing route requests, starting Active Guidance and monitoring navigation events. ## Unavailable features Some of the existing mechanisms in v2 are no longer officially supported. This may be changed in the future or worked around with other mechanics to achieve the same or similar effect. Feel free to reach out with suggestions or the use cases you'd like us to implement. Currently, next features are not available in v3 in comparison to v2: - Custom routing provider. - Route simulation speed control. To tweak the location source and simulation, see [`CoreConfig.locationSource`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/coreconfig/locationsource/). This setting can be used to enable location simulation or providing your own implementation. - Granular location updates and reroute attempts discarding. - Extending Mapbox standard Speech Synthesizers.