Tutorials

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

When integrating the Play Services location dependency (com.google.android.gms:play-services-location:20.0.0), it's essential to maintain version 20.0.0 or below. Starting from version 21.0.0, breaking changes have been introduced where some classes are now interfaces instead of classes, effective from October 13, 2022.

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.

1
<provider
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" />
9
</provider>

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

1
class 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
    }
7

8
    override fun dependencies(): List<Class<out Initializer<*>>> {
9
        return emptyList()
10
    }
11
}

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.

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

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

20
class NavigationActivity : FragmentActivity(),NavigationListener,RouteListener {
21

22
    private lateinit var navViewConfig: NavViewConfig
23
    override fun onCreate(savedInstanceState: Bundle?) {
24
        super.onCreate(savedInstanceState)
25
        val routes = intent.getSerializableExtra("routes") as? List<DirectionsRoute> ?: emptyList()
26

27
        navViewConfig = NavViewConfig.builder()
28
            .route(routes.first())
29
            .routes(routes)
30
            .navigationListener(this)
31
            .routeListener(this)
32
            .build()
33
        setContent {
34
            Surface(
35
                modifier = Modifier.fillMaxSize(),
36
                color = MaterialTheme.colors.background
37
            ) {
38
                NBNavigationView(
39
                    modifier = Modifier.fillMaxSize(),
40
                    initViewConfig = { _ ->
41
                        navViewConfig
42
                    })
43
            }
44
        }
45
    }
46

47
    override fun onCancelNavigation() {
48
        // The call back of on tap cancel button
49
        finish()
50
    }
51

52
    override fun onNavigationFinished() {
53
        // Callback when navigation finishes.
54
        // If not using simulated Navigation and the navigation finished, finish the activity as well
55
        if (!navViewConfig.shouldSimulateRoute()) {
56
            finish()
57
        }
58
    }
59

60
    override fun onNavigationRunning() {
61
        // Callback when navigation is running.
62
        // No action needed here.
63
    }
64

65
    override fun allowRerouteFrom(p0: Location?): Boolean {
66
        // Check whether need to reroute from the location, by default return true, if don't want to perform reroute, you can return false to interrupt it
67
       return true
68
    }
69

70
    override fun onOffRoute(p0: Point?) {
71
        // Callback when the user goes off route.
72
        // No action needed here.
73
    }
74

75
    override fun onRerouteAlong(p0: DirectionsRoute?) {
76
        // Callback when rerouting along a new route.
77
        // No action needed here.
78
    }
79

80
    override fun onFailedReroute(p0: String?) {
81
        // Callback when rerouting fails.
82
        // No action needed here.
83
    }
84

85
    override fun onArrival(p0: NavProgress?, p1: Int) {
86
        // Callback when the user arrives at their destination.
87
        // No action needed here.
88
    }
89

90
    override fun onUserInTunnel(p0: Boolean) {
91
        // Callback when the user is detected to be in a tunnel.
92
        // No action needed here.
93
    }
94

95
    override fun shouldShowArriveDialog(p0: NavProgress?, p1: Int): Boolean {
96
        // Check whether pop-up arrival dialog. If Dialog is not implemented in the customArriveDialog method, the default BottomSheetDialog is shown. If false is returned, Dialog is not displayed
97
      return false
98
    }
99

100
    override fun customArriveDialog(p0: NavProgress?, p1: Int): BottomSheetDialog? {
101
        // You can customize the arrival dialog if needed.
102
      return null
103
    }
104
}

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()
2
            …
3
            .build()

The parameter configuration and usage are as follows.

Required Parameters

Name	Description
`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

Name	Description
`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.

Example

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

1
NavViewConfig 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
6
        
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
19
        .instructionListListener(instructionListListener) // Set up the instruction list listener
20
        .speechAnnouncementListener(speechAnnouncementListener) // Set up the speech announcement listener
21
        .build();
22

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.