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 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 release with breaking API changes. If the application you are migrating uses a map, make sure you read the Maps SDK migration guide before reading the navigation-specific content below.
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
is no longer available and is replaced with CoreConfig
structure which consolidates all SDK configurations. It is now mandatory to provide this setting on SDK initialization. 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
contains some sub-structures which are designed to control dedicated use-cases.
MapboxNavigation
MapboxNavigation
is the main facade of the SDK. Comparing to v2 SDK it supersedes the NavigationService
and Router
. It handles the Navigator
, provides control over it as well as reporting navigation events.
Your typical interaction with the SDK starts like this:
let coreConfig = CoreConfig(/* ... */) // your configuration
let mapboxNavigationProvider = MapboxNavigationProvider(coreConfig: coreConfig)
let mapboxNavigation = mapboxNavigationProvider.mapboxNavigation
Lifecycle
MapboxNavigation
reference (or its 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
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
, Router
and PassiveLocationManager
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
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
, NavigationServiceDelegate
) 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
object.
Next is the list of available MapboxNavigation
components:
routingProvider()
Used to do route requests. It's functionality is equivalent to v2 RoutingProvider
.
It does not publish any events.
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:
-
Reports currently active navigation session state. This has no analogs in SDK v2.
-
Reports current
NavigationRoutes
set to the navigation. Can be used to replaceRouter.route
,NavigationService.route
orNavigationService.indexedRouteResponse
updates.
electronicHorizon()
This controller to toggle Electronic Horizon, and handle it's related road data.
Available events publishers:
-
Reports similar events to
electronicHorizonDidUpdatePosition
,electronicHorizonDidEnterRoadObject
,electronicHorizonDidExitRoadObject
andelectronicHorizonDidPassRoadObject
notifications.
navigation()
This controller focuses on Active Guidance mode, providing detailed control over related features and data.
Available events publishers:
-
Reports user heading updates. Replaces
Router.heading
property. -
Reports user location updates. Can be used to replace
Router
's andPassiveLocationManager
'srawLocation
andlocation
properties. -
Reports user progress along the route. Only available during the Active Guidance session. Replaces
RouterDelegate
s andNavigationServiceDelegate
sRouteProgress
update methods. -
Reports when navigator did switch tiles versions. Replaces
navigationDidSwitchToFallbackVersion
andnavigationDidSwitchToTargetVersion
notifications. -
Equivalent to
RouterDelegate.router(_:,didPassSpokenInstructionPoint:,routeProgress:)
andNavigationServiceDelegate.navigationService(_:,didPassSpokenInstructionPoint:,routeProgress:)
. -
Equivalent to
RouterDelegate.router(_:,didPassVisualInstructionPoint:,routeProgress:)
andNavigationServiceDelegate.navigationService(_:,didPassVisualInstructionPoint:,routeProgress:)
. -
Reports details about user arriving to a waypoint. Can be used to replace
RouterDelegate.router(_:,didArriveAt:)
orNavigationSerivce.navigationSerivce(_:,didArriveAt:)
. -
Reports details about the rerouting process. Replaces corresponding
RouterDelegate
andNavigationServiceDelegate
methods. -
Reports details about the continuous alternatives. Replaces
Router.continuousAlternatives
, correspondingRouterDelegate
andNavigationServiceDelegate
methods. -
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:)
orNavigationServiceDelegate.navigationService(_:,shouldProactivelyRerouteFrom:,to:,completion:)
. -
Reports route refreshing. Replaces
RouterDelegate.router(_:,didRefresh:)
orNavigationServiceDelegate.navigationService(_:,didRefresh:)
methods.
eventsManager()
This controller provides access to posting custom telemetry and feedback events. It does not publish any events.
historyRecorder()
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()
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
. It is equivalent to RoutingProvider
in SDK v2, with slightly different return result.
RoutingProvider
provides methods to get 'regular' Route Request as well as Map Matching Request. RoutingProvider
instance itself can be obtained from MapboxNavigation.routingProvider()
method.
Route objects
Navigation SDK v2 IndexedRouteResponse
and RouteResponse
are replaced with single 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
, now will be switched to 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
. 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.