# 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](/docs/navigation/sdk/android/customize-navigation-page)

## Set up your Identity (Optional)

### Configure User ID

```java
// Set user id
Nextbillion.setUserId("Your-User-Id");
```

```java

// Get user id, if you haven't set it, the value is null
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

```java
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](https://nextbillion.ai/) Navigation SDK that allows developers to customize the navigation engine. The following options can be configured:

| No. | Configuration option | Description |
| --- | --- | --- |
| 1 | maxTurnCompletionOffset | A step can be considered as completed If the offset between the user's current bearing and the maneuver’s expected bearing is smaller than this value. |
| 2 | maneuverZoneRadius | 1.  Users will be considered off-route if they move away from maneuvering more than this value<br>    <br>2.  Users will be considered to enter the maneuver, once their distances to the maneuver point are smaller than this value |
| 3 | enableOffRouteDetection | Enable or disable Off-Route detection |
| 4 | snapToRoute | Enable or disable Snap to road function |
| 5 | dynamicReroutingTolerance |  |
| 6 | timeFormatType | NONE_SPECIFIED, TWELVE_HOURS, TWENTY_FOUR_HOURS |
| 7 | roundingIncrement | The rounding increment of distance, available values: 5, 10, 25, 50, 100 |
| 8 | navigationNotification | Custom ongoing navigation notification, please refer to [Custom Navigation Notification](/docs/navigation/sdk/android/customization#custom-navigation-notification)  for more details. |

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](https://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.

| No. | Configuration option | Description |
| --- | --- | --- |
| 1 | route | The primary route rendered in the navigation UI/map. |
| 2 | lightThemeResId | Light theme for NavigationView |
| 3 | darkThemeResId | Dark theme for NavigationView |
| 4 | themeMode | light, dark or follow_system |
| 5 | shouldSimulateRoute | Enable or disable simulate navigation |
| 6 | waynameChipEnabled | Display wayname below the user puck |
| 7 | locationLayerRenderMode | -   NORMAL: Basic tracking is enabled, bearing ignored.<br>    <br>-   COMPASS: Tracking the user location with bearing from CompassEngine<br>    <br>-   GPS: Tracking the user location with bearing from Location |
| 8 | showSpeedometer | Show speedometer while in NavigationView |

## Launcher configuration

_NavLauncherConfig_ is the drop-in UI launch config, extending _NavUIConfig_ with launcher-specific options.

|  | Configuration option | Description |
| --- | --- | --- |
| 1 | routes | This option is used to set all the fetched routes that will be used in the navigation experience. |
| 2 | initialMapCameraPosition | This option is used to set the initial position of the camera when the navigation starts. |
| 3 | navigationMapStyle | This option is used to set the base map style of the NavigationView, which can be configured to match the desired look and feel of the application. |

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:

```java
NavViewConfig navViewConfig = NavViewConfig.builder()
                .milestoneEventListener(milestoneEventListener)
                .bannerInstructionsListener(bannerInstructionsListener)
                .speechAnnouncementListener(speechAnnouncementListener)
                .navigationListener(navigationListener)
                .routeListener(routeListener)
                .milestones(milestones)
                .route(route)
                .shouldSimulateRoute(true)
                .build();

navigationView.startNavigation(navViewConfig);
```

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

The options available include:

|  | Configuration option | Description |
| --- | --- | --- |
| 1 | routes | All fetched routes |
| 2 | NavEngineConfig | Configure the navigation engine |
| 3 | routeListener | Listen to all route-related events |
| 4 | navigationListener | Listen to all navigation-related events |
| 5 | progressChangeListener | Listen to the navigation progress change |
| 6 | milestoneEventListener | Listen to the triggered milestone events |
| 7 | milestones | Register self-defined milestones |
| 8 | bottomSheetCallback | Listen to the bottomsheet state changes of summary bottom sheet |
| 9 | instructionListListener | Listen to the visibility changes of instruction list |
| 10 | speechAnnouncementListener | intercept the speech announcement |
| 11 | bannerInstructionsListener | intercept the banner contents before they get rendered on the banner |
| 12 | speechPlayer | Custom speech player |
| 13 | locationEngine | Custom location engine |

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

```java
public interface RouteListener {

    boolean allowRerouteFrom(Location offRoutePoint);

    void onOffRoute(Point offRoutePoint);

    void onRerouteAlong(DirectionsRoute directionsRoute);

    void onFailedReroute(String errorMessage);

    void onArrival(NavProgress progress, int arrivedWaypointIndex);

    void onUserInTunnel(boolean inTunnel);

    boolean shouldShowArriveDialog(NavProgress progress, int arrivedWaypointIndex);

    BottomSheetDialog customArriveDialog(NavProgress progress, int arrivedWaypointIndex);
}
```

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

```java

public interface NavigationListener {

    /**
     * Will be triggered when the user clicks
     * on the cancel button while navigating.
     */
    void onCancelNavigation();

    /**
     * Will be triggered when NextbillionNav
     * has finished and the service is completely shut down.
     */
    void onNavigationFinished();

    /**
     * Will be triggered when NextbillionNav
     * has been initialized and the user is navigating the given route.
     */
    void onNavigationRunning();
}
```

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

```java
public interface ProgressChangeListener {
    void onProgressChange(Location location, NavProgress routeProgress);
}
```

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

```java
public interface MilestoneEventListener {
    void onMilestoneEvent(NavProgress routeProgress, String instruction, Milestone milestone);
}
```

### 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

```java
public interface InstructionListListener {
    /**
     * Will be called when the instruction list is shown or hidden.
     */
    void onInstructionListVisibilityChanged(boolean visible);

    //Internal use
    void onClickRestartButton(Location location);
}
```

_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

```java
public interface SpeechAnnouncementListener {

    /**
     * Listen to voice announcements that are about to be voiced.
     * Return null to ignore the given announcement
     */
    String willVoice(SpeechAnnouncement announcement);
}
```

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

```java
public interface BannerInstructionsListener {

    /**
     * Listen to BannerInstructions that are about to be displayed.
     * return null to ignore BannerInstructions
     */
    BannerInstructions willDisplay(BannerInstructions instructions);
}
```

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.