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

1
// Set user id
2
Nextbillion.setUserId("Your-User-Id");

1

2
// Get user id, if you haven't set it, the value is null
3
Nextbillion.getUserId();

• 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

1
Nextbillion.getNBId();

• 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:

Use NavEngineConfig to tune behavior such as step completion, off-route handling, reroute strategy, snap-to-route behavior, and navigation notification customization.

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. UI options include simulation mode, wayname chip, location render mode (NORMAL, COMPASS or GPS), and the speedometer toggle.

Launcher configuration

NavLauncherConfig is the drop-in UI launch config, extending NavUIConfig with launcher-specific options.

After configuration, start drop-in navigation by calling NavigationLauncher.startNavigation(activity, configBuilder.build()).

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:

1
NavViewConfig navViewConfig = NavViewConfig.builder()
2
                .milestoneEventListener(milestoneEventListener)
3
                .bannerInstructionsListener(bannerInstructionsListener)
4
                .speechAnnouncementListener(speechAnnouncementListener)
5
                .navigationListener(navigationListener)
6
                .routeListener(routeListener)
7
                .milestones(milestones)
8
                .route(route)
9
                .shouldSimulateRoute(true)
10
                .build();
11

12
navigationView.startNavigation(navViewConfig);

After building NavViewConfig, call navigationView.startNavigation(navViewConfig) to start embedded navigation with the configured options.

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.

1
public interface RouteListener {
2

3
    boolean allowRerouteFrom(Location offRoutePoint);
4

5
    void onOffRoute(Point offRoutePoint);
6

7
    void onRerouteAlong(DirectionsRoute directionsRoute);
8

9
    void onFailedReroute(String errorMessage);
10

11
    void onArrival(NavProgress progress, int arrivedWaypointIndex);
12

13
    void onUserInTunnel(boolean inTunnel);
14

15
    boolean shouldShowArriveDialog(NavProgress progress, int arrivedWaypointIndex);
16

17
    BottomSheetDialog customArriveDialog(NavProgress progress, int arrivedWaypointIndex);
18
}

RouteListener callbacks

• allowRerouteFrom(Location offRoutePoint) 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.
• onOffRoute(Point offRoutePoint) 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.
• onRerouteAlong(DirectionsRoute directionsRoute) 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.
• onFailedReroute(String errorMessage) method is called if the request for a new DirectionsRoute fails.
• onArrival(NavProgress progress, int arrivedWaypointIndex) method is called when a user has arrived at a given waypoint along a DirectionsRoute.
• onUserInTunnel(boolean inTunnel) method is called when the user’s tunnel status changes.
• shouldShowArriveDialog(...) method is used to control whether the arrival dialog should be shown when reaching a waypoint/destination.
• customArriveDialog(...) method provides a custom arrival dialog UI.
  • Return a custom BottomSheetDialog: SDK uses your dialog
  • Return null: SDK falls back to the default arrival dialog

navigationListener

NavigationListener is an interface that provides callbacks for events related to the navigation process. It includes three methods:

1. onCancelNavigation: This method is triggered when the user clicks on the cancel button while navigating.

2. onNavigationFinished: This method is triggered when the NextbillionNav has finished and the service is completely shut down.

3. 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.

1

2
public interface NavigationListener {
3

4
    /**
5
     * Will be triggered when the user clicks
6
     * on the cancel button while navigating.
7
     */
8
    void onCancelNavigation();
9

10
    /**
11
     * Will be triggered when NextbillionNav
12
     * has finished and the service is completely shut down.
13
     */
14
    void onNavigationFinished();
15

16
    /**
17
     * Will be triggered when NextbillionNav
18
     * has been initialized and the user is navigating the given route.
19
     */
20
    void onNavigationRunning();
21
}
22

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.

1
public interface ProgressChangeListener {
2
    void onProgressChange(Location location, NavProgress routeProgress);
3
}

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.

1
public interface MilestoneEventListener {
2
    void onMilestoneEvent(NavProgress routeProgress, String instruction, Milestone milestone);
3
}

milestones

NavViewConfig also accepts a list of milestones, Milestone is an abstract class, the built-in classes are:

1. BannerInstructionMilestone
2. 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

1
public interface InstructionListListener {
2
    /**
3
     * Will be called when the instruction list is shown or hidden.
4
     */
5
    void onInstructionListVisibilityChanged(boolean visible);
6

7
    //Internal use
8
    void onClickRestartButton(Location location);
9
}

NavigationView includes a built-in InstructionListListener to update UI elements (for example, the recenter button) when instruction list visibility changes.

Register only one custom InstructionListListener via NavViewConfig; built-in SDK handling executes before your callback.

speechAnnouncementListener

1
public interface SpeechAnnouncementListener {
2

3
    /**
4
     * Listen to voice announcements that are about to be voiced.
5
     * Return null to ignore the given announcement
6
     */
7
    String willVoice(SpeechAnnouncement announcement);
8
}
9

Triggered before a voice announcement is spoken. You can modify the speech announcement and return the updated value. The returned value is used for final voice playback.

bannerInstructionsListener

1
public interface BannerInstructionsListener {
2

3
    /**
4
     * Listen to BannerInstructions that are about to be displayed.
5
     * return null to ignore BannerInstructions
6
     */
7
    BannerInstructions willDisplay(BannerInstructions instructions);
8
}

Triggered before banner instructions are rendered, allowing content override. You can modify banner instruction content and return the updated value. The returned value is used for final banner rendering.