Choose an approach

The Mapbox Navigation SDK and Navigation UI SDK provide different ways to create a turn-by-turn navigation experience. Each approach has its own benefits and limitations. This guide will walk you through the options and provide some guidance on how to get started with each.

If you are new to Android development or are looking for the most efficient way to drop a pre-built navigation experience into your application, Mapbox offers an out-of-the box solution: the Navigation UI SDK's NavigationLauncher.

Benefits:

  • Quick to implement
  • Defaults that are appropriate for many typical navigation use cases
  • Ability to use either default or custom map styles for both day and night

Limitations:

  • Limited options for customization

Implement NavigationLauncher

The NavigationLauncher is a pre-built and non-customizable Android activity class. startNavigation takes a NavigationLauncherOptions object as input. This object in turn is instantiated with a directionsRoute object, which contains the turn-by-turn navigation information for a route. When startNavigation is called, it starts a new Android activity, which handles the instructions in the directionsRoute object and displays a complete turn-by-turn navigation experience using the current device location.

NavigationLauncher handles the layout, displaying turn-by-turn instructions, and route events (for example milestones, off-route detection, and re-routing). This means you do not need to configure this functionality manually, but it also means you cannot customize the experience.

example
Pre-built navigation experience

Launch a pre-built, non-customizable navigation experience with defaults that are appropriate for many typical navigation use cases.

If the only map in your application is used to facilitate a turn-by-turn navigation experience, Mapbox offers a more customizable approach: the Navigation UI SDK's NavigationView.

Benefits:

  • Broad set of customizable options
  • Predefined UI elements

Limitations:

  • NavigationView layout elements cannot be modified
  • No seamless access to the MapView's instance

Implement NavigationView

The NavigationView class extends the Android View class. NavigationView is similar to the Maps SDK's mapView class in terms of creating a map and customizing it. The difference is that navigation functionality is already built in and does not have to be added via the core Navigation SDK. After initialization of NavigationView, the startNavigation(NavigationViewOptions options) method can be called to start the turn-by-turn navigation experience on the initialized map.

example
Waypoint navigation

Create a customizable navigation experience with waypoints between destinations.

Collection of standalone components

If you want to build a completely customizable turn-by-turn experience, you can use the core Navigation SDK to build standalone navigation components on top of the Maps SDK for Android's MapView. This approach may also be appropriate if you'd like to integrate components of turn-by-turn navigation into an existing mapping application.

Benefits:

  • Completely customizable
  • Navigation can be done on same MapView that is used for other tasks

Limitations:

  • No out-of-the-box solution
  • Layout and function need manual implementation

Build a collection of components

The interplay of the Maps SDK's MapView and Navigation SDK's MapboxNavigation creates the most customizable approach to turn-by-turn navigation experiences. This combination brings together the mapView class, which allows for embedding highly customizable maps, and the full flexibility of the MapboxNavigation class. This allows you to customize every detail of the navigation experience without having to build it completely from scratch (using the Mapbox APIs directly).

Using this method requires building the following custom, standalone components to create a full turn-by-turn navigation experience:

  • Map: You will need to include a MapView element in your project's layout XML file. You can read more about how to customize MapView in the Maps SDK for Android documentation.
  • Route: Display a route on the map (Navigation UI SDK's NavigationMapRoute standalone component can be used).
  • Route events: A progressChangeListener can be attached, which implements callbacks on route events. An offRouteListener can also be attached. For maneuver instructions, a milestoneEventListener can be attached, so that maneuver instructions are fired once a maneuver point has been reached.
  • Instructions: To include an instructionView panel that displays instructions as needed along the route, you will need to include an InstructionView element in your project's layout XML file. This panel can also include navigation icons that show what maneuver to take next. Any icons can be used, but Mapbox offers an open set of icons.
  • Route summary: Most turn-by-turn navigation experiences also include a way to view a list of all instructions along with a summary of the distance and time required to complete the route (Navigation UI SDK's SummaryBottomSheet standalone component can be used).
  • Feedback: You should include a mechanism for users to provide feedback (Navigation UI SDK's FeedbackButton and FeedbackBottomSheet standalone components can be used).
example
Mock navigation

Use the Navigation SDK and Maps SDK to mock a navigation session using a mock location engine.

Was this page helpful?