• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places


Navigation SDK’s Android SDK levels For compatibility and optimal performance, ensure that your project adheres to the specified SDK version configurations.

  • minSdkVersion 21
  • targetSdkVersion 34
  • compileSdkVersion 34

Add Permissions

To unlock the full capabilities of the Navigation Compose SDK, ensure that your AndroidManifest.xml file includes the necessary permissions declaration. This step is crucial for enabling seamless functionality across various features and components provided by the SDK.

1<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
2<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
3<uses-permission android:name="android.permission.INTERNET" />
4// Runtime permissions
5<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
6<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
7<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Setting Up Access Key for NextBillion NavigationView

To enable access to the NextBillion NavigationView within your project, follow these steps:

Update AndroidManifest.xml

Locate the <application> tag in your project's AndroidManifest.xml file. Add a <provider> element inside it declaring androidx.startup.InitializationProvider, responsible for application initialization.

2 android:name="androidx.startup.InitializationProvider"
3 android:authorities="${applicationId}.androidx-startup"
4 android:exported="false"
5 tools:node="merge">
6 <meta-data
7 android:name=".AppDataInitStartup"
8 android:value="androidx.startup" />

Create AppDataInitStartup Class

Next, create a class named AppDataInitStartup in your project. This class should implement the Initializer<Boolean> interface. Within the create method of this class, perform the initialization tasks for your application. In this example, the initialization task is performed using Nextbillion.getInstance(context, "YOUR-ACCESS-KEY").

1class Application : Initializer<Boolean> {
2 override fun create(context: Context): Boolean {
3 SDKUtils.init(context as Application)
4 Nextbillion.getInstance(context, "YOUR-API-KEY")
5 return true
6 }
8 override fun dependencies(): List<Class<out Initializer<*>>> {
9 return emptyList()
10 }

Ensure to replace YOUR-ACCESS-KEY with your actual access key provided by NextBillion.ai.

By following these steps, you have added the code for AppDataInitStartup in your Android project. This code will be executed when the application starts, performing the initialization tasks defined in the create method.

Integrating NextBillion Navigation View into Your App

To seamlessly incorporate the NextBillion NavigationView into your application, follow this simple example utilizing the Compose extension:

1import ai.nextbillion.kits.directions.models.DirectionsRoute
2import ai.nextbillion.kits.geojson.Point
3import ai.nextbillion.maps.location.modes.RenderMode
4import ai.nextbillion.navigation.compose.NBNavigationView
5import ai.nextbillion.navigation.core.navigation.NavigationConstants
6import ai.nextbillion.navigation.core.navigator.NavProgress
7import ai.nextbillion.navigation.ui.NavViewConfig
8import ai.nextbillion.navigation.ui.listeners.NavigationListener
9import ai.nextbillion.navigation.ui.listeners.RouteListener
10import android.location.Location
11import android.os.Bundle
12import androidx.activity.compose.setContent
13import androidx.compose.foundation.layout.fillMaxSize
14import androidx.compose.material.MaterialTheme
15import androidx.compose.material.Surface
16import androidx.compose.ui.Modifier
17import androidx.fragment.app.FragmentActivity
18import com.google.android.material.bottomsheet.BottomSheetDialog

This example provides a comprehensive guide on integrating the NextBillion NavigationView into your app. Customize the provided methods as needed to tailor the navigation experience to your application's requirements. NavViewConfig Parameter Description

NavViewConfig is used to configure all parameters in the navigation process, including setting routes, route event listener, navigation monitoring, and so on. Initialization of this configuration is achieved through a builder pattern:

1 var navViewConfig = NavViewConfig.builder()
3 .build()

The parameter configuration and usage are as follows.

Required Parameters

route(DirectionsRoute directionsRoute)Sets the current navigation route.
routes(List<DirectionsRoute> directionsRoutes)Sets the list of navigation routes. The first route in the list corresponds to the primary route set via the route method, while the subsequent routes represent alternative options.
navigationListener(NavigationListener navigationListener)Establishes the navigation listener, allowing retrieval of navigation events. If employing NBNavigationView within a custom activity, ensure to finish the activity within the onCancelNavigation callback.

Optional Parameters

locationLayerRenderMode(int renderMode)Specifies the render mode for the location layer. The default is RenderMode.GPS.

Available values:
RenderMode.COMPASS, RenderMode.NORMAL, RenderMode.GPS
lightThemeResId(Integer lightThemeResId)Sets the light theme style ID, with the style parent being NavigationViewLight.
darkThemeResId(Integer darkThemeResId)Assigns the dark theme style ID, with the style parent being NavigationViewDark.
shouldSimulateRoute(boolean shouldSimulateRoute)Enables or disables simulation mode. The default is false.
waynameChipEnabled(boolean waynameChipEnabled)Toggles the visibility of the wayname chip. The default is true.
themeMode(String themeMode)Configures the navigation theme mode, which can be set as: NavigationConstants.NAVIGATION_VIEW_FOLLOW_SYSTEM_MODE, NavigationConstants.NAVIGATION_VIEW_DARK_MODE, or NavigationConstants.NAVIGATION_VIEW_LIGHT_MODE.

The default is NavigationConstants.NAVIGATION_VIEW_FOLLOW_SYSTEM_MODE.
navConfig(NavEngineConfig navConfig)Specifies the navigation engine configuration.
routeListener(RouteListener routeListener)Registers the route listener to capture navigation route events.
progressChangeListener(ProgressChangeListener progressChangeListener)Sets up the listener for navigation progress changes.
milestoneEventListener(MilestoneEventListener milestoneEventListener)Configures the milestone event listener.
milestones(List<Milestone> milestones)Customizes the milestones.
instructionListListener(InstructionListListener instructionListListener)Establishes the instruction list listener.
speechAnnouncementListener(SpeechAnnouncementListener speechAnnouncementListener)Sets up the listener for speech announcements.

By leveraging these parameters, you can fine-tune the behavior and appearance of the NextBillion NavigationView to suit your application's needs.


The following example demonstrates how to configure the parameters using the builder pattern.

1NavViewConfig navViewConfig = NavViewConfig.builder()
2 // Required Parameters
3 .route(primaryRoute) // Set the current navigation route
4 .routes(routeList) // Set the list of navigation routes
5 .navigationListener(navigationListener) // Set up the navigation listener
7 // Optional Parameters
8 .locationLayerRenderMode(RenderMode.GPS) // Set the location layer render mode
9 .lightThemeResId(R.style.NavigationViewLight) // Set the light theme style ID
10 .darkThemeResId(R.style.NavigationViewDark) // Set the dark theme style ID
11 .shouldSimulateRoute(false) // Enable or disable simulation mode
12 .waynameChipEnabled(true) // Enable or disable the wayname chip
13 .themeMode(NavigationConstants.NAVIGATION_VIEW_FOLLOW_SYSTEM_MODE) // Set the navigation theme mode
14 .navConfig(navEngineConfig) // Set the navigation engine configuration
15 .routeListener(routeListener) // Set up the route listener
16 .progressChangeListener(progressChangeListener) // Set up the navigation progress change listener
17 .milestoneEventListener(milestoneEventListener) // Set up the navigation milestone event listener
18 .milestones(customMilestones) // Custom the milestones

In this example, replace primaryRoute, routeList, navigationListener, RenderMode.GPS, R.style.NavigationViewLight, R.style.NavigationViewDark, false, true, NavigationConstants.NAVIGATION_VIEW_FOLLOW_SYSTEM_MODE, navEngineConfig, routeListener, progressChangeListener, milestoneEventListener, customMilestones, instructionListListener, and speechAnnouncementListener with appropriate instances or values according to your application's requirements.