Skip to main content

Migrate to Navigation SDK v3

Join the Mapbox Developers Discord Communityarrow-right

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

guide
Migrate to v11

Upgrade your application from the Mapbox Maps SDK for iOS v10 to v11.

chevron-right

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 MapboxNavigations 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:

electronicHorizon()​

This controller to toggle Electronic Horizon, and handle it's related road data.

Available events publishers:

This controller focuses on Active Guidance mode, providing detailed control over related features and data.

Available events publishers:

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.

Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?