SDK Configuration and Integration
The Nextbillion.AI Navigation SDK allows developers to customize their navigation experience through configuration systems. There are three types of configurations available:
-
NavLauncherConfig: configurations to launch navigation in drop-in UI.
-
NavViewConfig: configurations of Navigation View.
-
NavEngineConfig: configurations of Navigation Engine.
Developers have the option to choose between two approaches when starting a navigation experience:
-
Use the NavLauncherConfig to launch navigation in the SDK's drop-in UI, with limited customization options.
-
Embed the NavigationView into an Activity or Fragment for a more personalized experience, allowing for further customization of NavViewConfig and NavEngineConfig.
For more information about Embedded NavigationView, please refer to Custom Navigation Page
Set up your Identity (Optional)
Configure User ID
- This feature allows developers to integrate their existing user ID system with the Nextbillion SDK. this ID will then be included in the user-agent header sent to the backend service.
- To set a custom user ID from your account system, use the Nextbillion.setUserId("Your-User-Id") method.
- You can retrieve the set user ID using Nextbillion.getUserId().
Retrieve Nextbillion ID
- The SDK also generates a unique identifier called the Nextbillion ID.
- You can retrieve the Nextbillion ID using the Nextbillion.getNBId().
Navigation Engine configuration
NavEngineConfig is a configuration option in the Nextbillion.AI Navigation SDK that allows developers to customize the navigation engine. The following options can be configured:
UI Configuration
The UI Configuration “NavUIConfig” in the Nextbillion.AI Navigation SDK allows developers to customize the appearance and behavior of the navigation view. It includes options to set the primary route to be rendered on the map view, the light and dark theme for the navigation view, and the theme mode to be used. Developers can also enable or disable the simulation of the route and the wayname chip, which displays the name of the current road below the user's location. Additionally, developers can choose the location layer render mode, which can be set to NORMAL, COMPASS, or GPS. Finally, developers can also enable or disable the speedometer while in the navigation view. These options provide developers with flexibility and control over the look and feel of the navigation experience.
Launcher configuration
NavLauncherConfig is a configuration class used to launch the navigation experience in Nextbillion.AI Navigation SDK's drop-in UI. It is a child class of NavUIConfig, which means it inherits all the properties of NavUIConfig. Developers can use NavLauncherConfig to set options such as routes
, initialMapCameraPosition
, and navigationMapStyle
.
Once the configurations are set, developers can then use NavigationLauncher.startNavigation(activity, configBuilder.build()) method to launch the navigation experience with the desired configurations.
View configuration
The NavViewConfig is used to configure the settings for NavigationView and is required when starting navigation with embedded NavigationView. It can be built by using the NavViewConfig.Builder class, which allows developers to set various options such as the route, milestones, and listeners for different events. When we start navigation with NavigationView, a NavViewConfig is required, below is how we build a NavViewConfig with the relevant builder:
Once the NavViewConfig is built, developers can call the startNavigation() method on the NavigationView object, passing in the NavViewConfig. This will start the navigation experience using the settings specified in NavViewConfig.
The options available include:
routeListener
A listener that hooks into route related events. This is an interface that allows developers to hook into various route-related events during navigation. The interface includes several callback methods that are triggered at different points in the navigation process.
The allowRerouteFrom
method is called when the user goes off-route, it allows the developer to decide whether to fetch a new route with the given off-route location or not. The onOffRoute
method is called only if allowRerouteFrom
returns true and serves as the official off-route event, it continues the process to fetch a new route with the given off-route location. The onRerouteAlong
method is called when a new DirectionsRoute has been retrieved after going off-route, this is the new route the user will be following until another off-route event is triggered. The onFailedReroute
method is called if the request for a new DirectionsRoute fails. Lastly, the onArrival
method is called when a user has arrived at a given waypoint
along a DirectionsRoute.
navigationListener
NavigationListener is an interface that provides callbacks for events related to the navigation process. It includes three methods:
-
onCancelNavigation: This method is triggered when the user clicks on the cancel button while navigating.
-
onNavigationFinished: This method is triggered when the NextbillionNav has finished and the service is completely shut down.
-
onNavigationRunning: This method is triggered when NextbillionNav has been initialized and the user is navigating the given route. It allows developers to listen to the navigation progress and to perform certain actions based on the current status of the navigation.
progressChangeListener
Each time the SDK receives a new location update, the navigation progress will be updated and the updated progress will be sent to all ProgressChangeListeners.
milestoneEventListener
MilestoneEventListener is a listener that hooks into milestone events. A milestone is a point in the route navigation where a specific event happens. This can include passing a particular point, reaching a certain distance, or arriving at a destination. The onMilestoneEvent method is called when a milestone event occurs, providing the current route progress, a string instruction, and the milestone that was triggered. The developer can use this information to perform custom actions such as updating UI, playing sound, or sending notifications.
milestones
NavViewConfig also accepts a list of milestones, Milestone is an abstract class, the built-in classes are:
- BannerInstructionMilestone
- VoiceInstructionMilestone
We can plot milestones by instantiating built-in milestones or creating our own, but the SDK can only handle built-in milestones. To handle our own milestones, we need to register MilestoneEventListener to capture the milestones and perform expected actions.
instructionListListener
There is a built-in implementation in the NavigationView, it listens to the visibility change event of the instruction list to update the Navigation UIs such as the Recenter Button.
Developers can only configure one implementation and register it via the NavViewConfig, the event will be cascaded from the built-in implementation to the developers' implementation.
speechAnnouncementListener
This listener will be triggered when a voice announcement is about to be voiced. The listener gives you the option to override any values and pass them as the return value, which will be the value used for the voice announcement.
bannerInstructionsListener
This listener will be triggered when a BannerInstructions is about to be displayed. The listener gives you the option to override any values and pass them as the return value, which will be the value used for the banner instructions.