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:

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:

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);

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.

1
public interface RouteListener {
2

3

4
    /**
5
     * Will be triggered when the user goes off-route.
6
     * Returning true: fetch a new route with this given off-route location
7
     * Returning false: the user will continue without a new route in the
8
     * direction they are traveling.
9
     */
10
    boolean allowRerouteFrom(Point offRoutePoint);
11

12
    /**
13
     * Will be triggered only if allowRerouteFrom returns true.
14
     * This serves as the official off-route event and will continue the process to fetch a new route
15
     * with the given off-route location
16
     */
17
    void onOffRoute(Point offRoutePoint);
18

19
    /**
20
     * Will trigger when a new DirectionsRoute has been retrieved after off route.
21
     * This is the new route the user will be following until another off-route event is triggered.
22
     */
23
    void onRerouteAlong(DirectionsRoute directionsRoute);
24

25
    /**
26
     * Will trigger if the request for a new DirectionsRoute fails.
27
     */
28
    void onFailedReroute(String errorMessage);
29

30
    /**
31
     * Will trigger when a user has arrived at a given waypoint along a DirectionsRoute.
32
     * For example, if there are two {@link LegStep}s, this callback
33
     * will be triggered twice, once for each waypoint.
34
     */
35
    void onArrival();
36
}

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:

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
}

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

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

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

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
}

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.