Migrate UI | Navigation SDK v3 | iOS

The following article outlines the main API changes for the UI components and aims to help with the migration to the MapboxNavigationUIKit (former MapboxNavigation) library.

EXAMPLE

UIKitExample

mapbox-navigation-ios repository provides UIKitExample showing how to use the UI components.

Requirements

MapboxNavigationUIKit requires an iOS target to be iOS 14 or higher.

MapboxCoreNavigation migration

MapboxNavigationUIKit builds on MapboxNavigationCore. Visit the MapboxCoreNavigation migration guide to find out how to migrate to MapboxNavigationCore.

MapboxNavigation migration

A library that provides a suite of UI components has been renamed from MapboxNavigation into MapboxNavigationUIKit. MapboxNavigationUIKit contains the same UI components that were included into MapboxNavigation from Navigation SDK v2. The UI components included into MapboxNavigationUIKit have adopted a new generation of navigation core functionality that is provided by MapboxNavigationCore library (former MapboxCoreNavigation).

`NavigationViewController`

Replace the old NavigationViewController initializer with a new NavigationViewController.init(navigationRoutes: NavigationRoutes, navigationOptions: NavigationOptions):

navigationRoutes parameter contains the main and alternative routes and can be obtained via RoutingProvider.
navigationOptions parameter contains customization options for the turn-by-turn navigation user experience and can be constructed using a new MapboxNavigation protocol.

An example of instantiating NavigationViewController using a routes response from RoutingProvider:


let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())
do  {
  let navigationRouteOptions = NavigationRouteOptions(coordinates: coordinates)
  let routesResponse = try await navigationProvider.routingProvider().calculateRoutes(options: navigationRouteOptions).value
  NavigationViewController(
    navigationRoutes: routesResponse,
    navigationOptions: NavigationOptions(
      mapboxNavigation: navigationProvider.mapboxNavigation,
      voiceController: navigationProvider.routeVoiceController,
      eventsManager: navigationProvider.eventsManager(),
      styles: [NightStyle()],
      predictiveCacheManager: navigationProvider.predictiveCacheManager
    )
  )
} catch {
  print("Error occured while requesting routes: \(error.localizedDescription)")
}

`NavigationView`

Replace the old NavigationView initializer with a new NavigationView.init(frame: CGRect, mapViewConfiguration: MapViewConfiguration). MapViewConfiguration allows you to re-use existing NavigationMapView or create a new one. If you choose to create a new NavigationMapView you need to provide a list of dependencies that can be obtained from MapboxNavigation protocol.

An example of instantiating NavigationView that creates a new NavigationMapView:


let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

NavigationView(
  frame: .zero,
  mapViewConfiguration: .createNew(
    location: navigationProvider.navigation().locationMatching
      .map(\.mapMatchingResult.enhancedLocation)
      .eraseToAnyPublisher(),
    routeProgress: navigationProvider.navigation().routeProgress
      .map(\.?.routeProgress)
      .eraseToAnyPublisher(),
    predictiveCacheManager: navigationProvider.predictiveCacheManager
  )
)

`NavigationMapView`

Note: NavigationMapView has been moved into the MapboxNavigationCore library.

Initialize NavigationMapView using NavigationMapView.init(location: AnyPublisher<CLLocation, Never>, routeProgress: AnyPublisher<RouteProgress?, Never>, navigationCameraType: NavigationCameraType, heading: AnyPublisher<CLHeading, Never>?, predictiveCacheManager: PredictiveCacheManager?). Those dependencies can be obtained from MapboxNavigation protocol.

An example of instantiating NavigationMapView:


let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

NavigationMapView(
  location: navigationProvider.navigation().locationMatching
    .map(\.mapMatchingResult.enhancedLocation)
    .eraseToAnyPublisher(),
  routeProgress: navigationProvider.navigation().routeProgress
    .map(\.?.routeProgress)
    .eraseToAnyPublisher(),
  heading: navigationProvider.navigation().heading,
  predictiveCacheManager: navigationProvider.predictiveCacheManager
)

`PreviewViewController`

Initialize PreviewViewController using PreviewViewController.init(_: PreviewOptions). PreviewOptions requires you to provide dependencies that can be obtained from MapboxNavigation protocol.

An example of instantiating PreviewViewController:


let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

PreviewViewController(
  PreviewOptions(
    locationMatching: navigationProvider.navigation().locationMatching,
    routeProgress: navigationProvider.navigation().routeProgress
      .map(\.?.routeProgress)
      .eraseToAnyPublisher(),
    predictiveCacheManager: navigationProvider.predictiveCacheManager
  )
)