> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/v2/llms.txt)

# Copilot

> **Note (beta): Developer Preview**
> 
> Copilot is now in a Developer Preview state. The feature is being actively updated, so the interfaces might change, but we're excited to share it with the community and receive your feedback.

Mapbox Copilot is a Navigation SDK component that collects detailed trace files of navigation sessions together with search analytics data. The Copilot library processes full-trip-trace longitude and latitude data ("**Copilot**").

Copilot collects information that helps you in two different ways:

-   It makes driver feedback more actionable.
-   It provides Mapbox teams with the necessary information to investigate and resolve driver-reported issues and, consequently, helps speed up SDK updates that improve the driver experience for the entire developer community.

## Opt-in feature

Copilot is an opt-in feature, so it is turned off by default. You have the choice to enable it at the application-developer level for your users (drivers) to improve feedback resolution. See the [*Lifecycle* section](https://docs.mapbox.com/android/navigation/v2/guides/copilot/#lifecycle) below for technical details.

Depending on the use case, you can enable Copilot for either all drivers (for example, during a pilot) or a subset of them.

If you enable Copilot, your organization is in charge of obtaining and maintaining all necessary consents and permissions, including providing notice to and obtaining your end users' affirmative, expressed consent before any access or use of Copilot.

> **Note (warning): Informing end users**
> 
> As the application developer, you are responsible for communicating to drivers about the data that is being collected from their drives, including what kind of data is being collected and when it is collected.

## Installation

Add the library dependency to your `build.gradle`:

```groovy
dependencies {
  implementation "com.mapbox.navigation:copilot:2.22.2"
}
```

If you use the `com.mapbox.navigation:android` artifact, you do not need to add the `copilot` dependency explicitly as it is bundled with the rest of the Navigation SDK's features.

## Lifecycle

Copilot is a [`MapboxNavigationObserver`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.lifecycle/-mapbox-navigation-observer/), so it's tied to the [`MapboxNavigation`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-mapbox-navigation/) lifecycle automatically.

We recommend connecting the [`MapboxCopilot.start`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-mapbox-copilot/start.html) and [`MapboxCopilot.stop`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-mapbox-copilot/stop.html) APIs to your app's lifecycle.

> **Note (warning): Not integrating MapboxNavigationApp yet?**
> 
> Not a problem! If you do not integrate [`MapboxNavigationApp`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.lifecycle/-mapbox-navigation-app/) you should replace your occurrences of `start` / `stop` by [`MapboxCopilot.onAttached`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-mapbox-copilot/on-attached.html) / [`MapboxCopilot.onDetached`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-mapbox-copilot/on-detached.html) respectively.

We also recommend tracking the [`DeveloperMetadata.copilotSessionId`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-developer-metadata/copilot-session-id.html) (see [`DeveloperMetadataObserver`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-developer-metadata-observer/)) so that Mapbox teams can better act on specific end-user feedback. This ID helps Mapbox teams find the respective traces and troubleshoot issues faster.

Register the `DeveloperMetadataObserver` interface with [your already-instantiated `MapboxNavigation` object](https://docs.mapbox.com/android/navigation/v2/guides/get-started/initialization/).

```kotlin
mapboxNavigation.registerDeveloperMetadataObserver(developerMetadataObserver)
```

Also, remember to unregister the `DeveloperMetadataObserver` interface.

```kotlin
override fun onStop() {
	super.onStop()
    mapboxNavigation.unregisterDeveloperMetadataObserver(developerMetadataObserver)
}
```

Noting that the `DeveloperMetadata.copilotSessionId` is generated internally based on the current state within a history recording session and will change when transitioning across states of a trip session (it's empty when the [`NavigationSessionState`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.trip.session/-navigation-session-state/) is [`Idle`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.trip.session/-navigation-session-state/-idle/)). As in your Copilot lifecycle is not tied to `MapboxNavigation` / `NavigationSessionState`, the `copilotSessionId` will be the same even after calling `start` (`onAttached`) / `stop` (`onDetached`) APIs.

## Options: How data is collected

Nav SDK exposes configuration settings (see [`NavigationOptions.copilotOptions`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-base/com.mapbox.navigation.base.options/-navigation-options/copilot-options.html)) to use Copilot in two ways:

1.  **Automatic** data collection: Enable Copilot for all trips performed by a specific driver (default option).
2.  **Manual** data collection: Copilot data is only sent when an end user submits negative feedback about a specific route to help take action on the issue.

```kotlin
val navigationOptions = NavigationOptions.Builder(this)
    .accessToken("YOUR_ACCESS_TOKEN")
    .copilotOptions(
        // Set shouldSendHistoryOnlyWithFeedback to true if you want to sent Copilot traces only when an end user submits negative feedback
        // By default shouldSendHistoryOnlyWithFeedback is false so there is no need to add CopilotOptions if you want automatic data collection
        CopilotOptions.Builder().shouldSendHistoryOnlyWithFeedback(true).build()
    ).build()
```

## Feedback

Data collection for Copilot is tightly coupled to the Navigation SDK Feedback, which means this is only effective if the feedback events are pushed through [`MapboxNavigation`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-mapbox-navigation/) Feedback APIs.

> **Note: More on Feedback**
> 
> For more details on how *Feedback* works, see the [*Feedback* documentation](https://docs.mapbox.com/android/navigation/v2/guides/feedback/).

## Search events

If you would like to provide search analytics into Copilot, you can send the search events over to Copilot (see [`MapboxCopilot.push`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-mapbox-copilot/push.html)). This information would include whether a routable point for navigation was available. Copilot helps understand the impact of search results to a navigation session (arrival experience, routable points).

There are two types of events that can be pushed:

-   [`SearchResultsEvent`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-search-results-event/)

```kotlin
// Push a SearchResultsEvent every time a search results response is retrieved.
MapboxCopilot.push(
    SearchResultsEvent(
        SearchResults("mapbox", "https://mapbox.com", null, null, "?query=test1", null)
    )
)
```

-   [`SearchResultUsedEvent`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-copilot/com.mapbox.navigation.copilot/-search-result-used-event/)

```kotlin
// Push a SearchResultUsedEvent every time a search result is selected.
MapboxCopilot.push(
    SearchResultUsedEvent(
        SearchResultUsed(
            "mapbox",
            "test_id",
            "mapbox_poi",
            "mapbox_address",
            HistoryPoint(-77.03396910343713, 38.89992797324407),
            null,
        )
    )
)
```

> **Note: More on Mapbox Search SDK**
> 
> Any search provider can be used with Copilot, including the Mapbox Search SDK. For more details on how the Mapbox Search SDK works, see the [Search SDK Integration documentation](https://docs.mapbox.com/android/navigation/v2/guides/advanced/searchsdk-integration/).

## Example

> **Related content (example): [Copilot](https://docs.mapbox.com/android/navigation/v2/examples/copilot/)**
> 
> Learn how to integrate `MapboxCopilot` with your application.