Feedback Agent
Collect feedback and turn it into actionable insights. Feedback Agent helps you understand user needs faster and improve your product quickly — right inside your app.
How to Enable Feedback Agent
To enable Feedback Agent in Navigation SDK, follow these steps:
Step 1: Add the dependency
Add the following dependencies to your app-level build.gradle
file:
implementation("com.mapbox.navigationcore:navigation:3.11.0")
implementation("com.mapbox.navigationcore:core-mapgpt:3.11.0")
implementation("com.mapbox.mapgpt.experimental:mapgpt:24.14.0")
Step 2: Implement core classes
To integrate Feedback Agent with the Navigation SDK, you need to implement the following core classes:
// 1. Create the ASR service implementation
internal class MapboxASRServiceImpl(
private val voiceFeedbackContextProvider: VoiceFeedbackContextProvider = StubVoiceFeedbackContextProvider(),
private val languageRepository: LanguageRepository = LanguageRepositoryImpl(),
private val profileId: String = DEFAULT_FEEDBACK_PROFILE_ID,
private val cancelTimeout: Duration = DEFAULT_CANCEL_TIMEOUT,
private val coroutineScope: CoroutineScope = GlobalScope,
private val jsonDecoder: Json = Json { ignoreUnknownKeys = true },
) : MapboxASRService {
private val mapgptSession: MapgptSession = MapgptSession()
override val asrData = MutableSharedFlow<AsrData?>(
extraBufferCapacity = 1,
onBufferOverflow = BufferOverflow.DROP_OLDEST,
)
override val sessionState = MutableStateFlow<SessionState>(SessionState.Disconnected)
override fun connect() {
val endpoint = getNativeMapgptEndpoint()
// Connect to MapGPT service for cloud ASR functionality here
// See provided example app for details
}
override fun startAsrRequest() {
val voiceFeedbackJsonContext = voiceFeedbackContextProvider.getJsonContext()
if (voiceFeedbackJsonContext != null) {
ValueConverter.fromJson(voiceFeedbackJsonContext).onValue { context ->
val traceId = MapgptEventsService.generateTraceId()
mapgptSession.startAsrRequest(context, emptyList(), profileId, traceId)
}
}
}
override fun sendAsrData(data: ByteArray) {
mapgptSession.sendAsrData(data)
}
}
// 2. Create the automatic speech recognition engine
@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
internal class MapboxAutomaticSpeechRecognitionEngine(
private val mapboxASRService: MapboxASRService = MapboxASRServiceImpl(),
private val microphoneMiddleware: LiteMicrophoneMiddleware,
private val mainScope: CoroutineScope = MainScope(),
private val ioScope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.IO),
) : AutomaticSpeechRecognitionEngine {
override val state = MutableStateFlow<ASRState?>(null)
override fun startListening() {
mapboxASRService.startAsrRequest()
state.value = ASRState.Listening("")
}
override fun stopListening() {
state.value = ASRState.Idle
mapboxASRService.finishAsrRequest()
microphoneMiddleware.stop()
}
override fun connect() {
mapboxASRService.connect()
}
}
// 3. Create the ViewModel with feedback handling
@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
internal class VoiceFeedbackViewModel : ViewModel() {
private val microphoneMiddleware = AudioLiteMicrophoneMiddleware()
private val engine: AutomaticSpeechRecognitionEngine = MapboxAutomaticSpeechRecognitionEngine(
microphoneMiddleware = microphoneMiddleware,
)
private val _viewState = MutableStateFlow(VoiceFeedbackViewState())
val viewState: StateFlow<VoiceFeedbackViewState> = _viewState.asStateFlow()
init {
// Handle ASR state changes and process feedback results
engine.state.onEach { asrState ->
when (asrState) {
is ASRState.Result -> {
val feedbackType = asrState.text
val feedbackDescription = asrState.feedbackType
postUserFeedback(feedbackType, feedbackDescription)
}
// Handle other ASR states here.
}
}.launchIn(viewModelScope)
}
fun onConnectClicked() = engine.connect()
fun onStartListeningClicked() = engine.startListening()
fun onStopListeningClicked() = engine.stopListening()
}
Step 3: Get the Feedback ID for an item
The Feedback SDK automatically generates a feedback ID for every feedback item. You can optionally track this value to close the feedback loop with your users and notify them when one of their items has been closed, for example. For more information, see Closing the Feedback Loop.
private suspend fun postUserFeedback(feedbackType: String, feedbackDescription: String) {
val userFeedback = UserFeedback.Builder(FeedbackEvent.VOICE_FEEDBACK, feedbackDescription)
.feedbackSubTypes(listOf(feedbackType))
.build()
val mapboxNavigation = MapboxNavigationApp.waitUntilInitialized()
mapboxNavigation.postUserFeedback(userFeedback) { result ->
// The result contains the feedbackId for tracking purposes
// Optional: Store this feedbackId to close the feedback loop with users
SharedLog.d("VoiceFeedbackViewModel") { "feedbackId: ${result.feedbackId}" }
}
}
This example includes a complete Android application integrating Feedback Agent.
Feedback Explorer
The Feedback Explorer inside the Mapbox Console is the easiest mechanism to visualize the items from the users in your application:
Tapping on a feedback item will give you all the details, including a map with the location of the report:
The Feedback Explorer allows you to:
- Browse all feedback items from users of your application.
- View the category generated by the Feedback Agent (see list below), the date of the item, the transcription, the resolution state, and the location of the item.
- Filter items by date, category, or status (one of
open
,acknowledged
,fixed
,unreproducible
,unactionable
,unsupported
). - Tap on an individual item to get all its information, including a map of the location of the item.
Default Categories
By default, Feedback Agent provides a set of default categories for location-related items:
Category | Description |
---|---|
alternative_route_issue | To report wrong or missing alternative route. |
banner_issue | Problems with the given banners. |
eta_issue | Problems with ETA quality. |
false_negative_traffic_issue | When a user reports traffic congestion or delays (e.g., traffic jams or traffic build up) |
false_positive_traffic_issue | When a user reports traffic is flowing smoothly and there's no congestion |
guidance_issue | Problems with the given guidance. |
illegal_entrance | When a suggested entrance is illegal. |
illegal_turn | When a suggested turn is illegal. |
lane_guidance_issue | Issues specifically around lane guidance or details about the road as displayed on the map. |
map_data_issue | Problems with map features and functionality. |
map_rendering_issue | Problems with map rendering. |
missing_expected_maneuver | When a legal turn is not suggested. |
no_route | When a route is not built. |
poi_closed | When a user reports that a place on the map or navigation no longer exists. |
poi_details | When a user reports that details about a place are incorrect or need to be updated. |
poi_location | When a user reports that location about a place is incorrect. |
poi_missing | Problems with the assistant's ability to find POIs, addresses, or other places. |
police_speed_trap | When a user reports a police speed checkpoint. |
poor_arrival_issue | To report issues with arrival behavior. |
poor_routing_issue | Problems with the given route. |
positioning_issue | Problems with a puck/location of car and matching to the current roads. |
rerouting_recalculation | To report continuous or incorrect rerouting/route recalculation. |
road_closure_issue | When a road is closed temporarily or permanently. |
road_incident_issue | Problems with road incident. |
speed_limit_issue | To report wrong or missing speed limit data. |
traffic_issue | When the user wants to report traffic, congestion or incidents like trash in the road. |
voice_guidance_issue | Problems with the given voice guidance. |
application_issue | Capture issues with application performance, bugs, or errors unrelated to specific navigation features. |
non_feedback | Irrelevant or nonsensical feedback that does not pertain to application functionality or navigation issues. |
Mapbox will automatically triage and act on these items on your behalf to improve the underlying data based on items from users of your application.
Custom Categories
Besides the default categories mentioned above, Feedback Agent provides a generic application_issue
category to capture issues with application performance, bugs, or errors unrelated to specific navigation features.
If you need more fine-grained application-related categories, you can also define your own. For example, a food delivery application might want to collect specific information about food_packaging
.
For more information on how to create custom categories, see contact us.
Closing the Feedback Loop
When using Feedback Agent you can close the feedback loop with the user that submitted an item, by notifying them that their feedback has been received and its current status. At a high level, the process will be as follows:
- Get the
feedbackId
from the Feedback SDK. This is a unique identifier string automatically generated by the Feedback SDK. - Store this value in your system associated with a specific logged-in user in your app.
- Use the Mapbox Feedback API to query the status of the item using its
feedbackId
. - When the status changes, use a dedicated screen, a push notification, email, or any other relevant mechanism to notify the user.
Feedback API
The Mapbox Feedback API provides a unified, programmatic way to access end user feedback collected from the apps you build with Mapbox.
This API allows you to integrate feedback data directly into your own internal tools and data pipelines, giving you visibility into the issues and suggestions your users provide. You can track the status of feedback items as they are reviewed by Mapbox and get valuable insights about your applications.
In particular, the Feedback API allows querying items by feedbackId
to close the feedback loop with your users.
Pricing Information
Feedback Agent is free during the Public Preview, including access to Feedback Explorer and the Feedback API.
At General Availability, customers using Feedback Agent will incur a charge of $0.02 per feedback item, with data retained only for a limited period. This charge includes access to Feedback Explorer and the Feedback API.
For custom categories, contractual service level agreements (SLAs) on map and navigation feedback resolution, or advanced reporting, contact us.