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

# Feedback Agent

# Feedback Agent

> **Note (beta): Public Preview for Feedback Agent**
> 
> Feedback Agent is available in Public Preview. During this phase, it may be subject to potential breaking changes as the features and API surfaces stabilize.

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.

![Navigation application on iOS showing a voice box recording feedback.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-guides-mapgpt-feedback-agent.480.gif)

## How to Enable Feedback Agent

To enable Feedback Agent in Navigation SDK, follow these steps:

> **Related content (guide): [Navigation 'Get Started' Guide](https://docs.mapbox.com/ios/ja/navigation/guides/install/)**
> 
> For new projects you may need to follow the Navigation "Get Started" guide to configure your Mapbox access token and project settings.

### Step 1: Add the dependency

Add the following dependencies to your Xcode Package Dependencies or Package.swift

```swift
dependencies: [
    .package(url: "https://github.com/mapbox/mapbox-navigation-ios.git", exact: 3.29.0),
    .package(url: "https://github.com/mapbox/mapbox-mapgpt-ios.git", exact: 3.17.0-alpha.1),
],
```

### Step 2: Instantiate MapGptSession

To integrate Feedback Agent with the Navigation SDK, you need to instantiate a `MapGptSession` and provide it with a `Recorder` object and a `MapboxNavigationProvider.eventsManager` object.

```swift
import MapboxCommon
import SwiftUI
@_spi(ExperimentalMapboxAPI) import MapboxMapGpt
import MapboxNavigationCore

@main
struct MapGptExampleApp: App {
    init() {
        let localRecorder = Recorder()
        self._recorder = StateObject(wrappedValue: localRecorder)
        self.navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())
        let eventsManager = navigationProvider.eventsManager
        self._gptSession = StateObject(
            wrappedValue: MapGptSession(
                eventsManager: eventsManager(),
                recorder: localRecorder
            )
        )
    }

    var navigationProvider: MapboxNavigationProvider
    @StateObject var recorder: Recorder
    @StateObject var gptSession: MapGptSession

    var body: some Scene {
        WindowGroup {
            TabView {
                ExampleContentView(mapGptSession: gptSession)
                    .tabItem {
                        Label("MapGpt", systemImage: "message.badge.waveform")
                    }
            }
        }
    }
}
```

### Step 3: Provide MapGptSession to VoiceFeedbackView

Now you can create a view that will present `VoiceFeedbackView` in a sheet to use the MapGptSession Feedback Agent pre-built UI:

```swift
import AVFoundation
import Combine
import CoreLocation
import CoreLocationUI
import MapboxCommon
@_spi(ExperimentalMapboxAPI) import MapboxMapGpt
@_spi(ExperimentalMapboxAPI) import MapboxMapGptUI
import MapboxNavigationCore
import SwiftUI

struct ExampleContentView: View {
    @StateObject var locationManager = LocationManager()

    @ObservedObject var mapGptSession: MapGptSession

    @State var showFeedbackAgentSheet: Bool = false
    @State var sessionStatusDescription = "_"

    var body: some View {
        VStack(spacing: 20) {
            LocationButton {
                locationManager.setup()
            }
            .foregroundStyle(Color(.systemBackground))
            .clipShape(RoundedRectangle(cornerRadius: 10))
            .overlay(alignment: .trailing) {
                if locationManager.loading {
                    ProgressView()
                        .offset(x: 26)
                }
            }

            Text(sessionStatusDescription)
            HStack {
                Text("State:")
                Spacer()
                Text(mapGptSession.state.display)
            }
            .padding(.horizontal)

            VStack {
                Button("Present Feedback Agent sheet") {
                    showFeedbackAgentSheet = true
                }
            }
            .disabled(!mapGptSession.ready)

            Spacer()

            List {
                ForEach(mapGptSession.transcriptContents, id: \.hashValue) { transcript in
                    Text(transcript)
                }
            }
        }
        .sheet(isPresented: $showFeedbackAgentSheet) {
            VoiceFeedbackView(
                sessionObserver: mapGptSession
            ) {
                showFeedbackAgentSheet = false
            } completion: { result in
                showFeedbackAgentSheet = false
                // Note: Result<VoiceFeedbackItem, Error> will contain the feedback ID and automatic-speech recognition text of the report.
            }
        }
        .onChange(of: locationManager.currentLocation) { newValue in
            mapGptSession.userContext = Context(
                location: newValue
            )
        }
    }
}

class LocationManager: NSObject, ObservableObject {
    private(set) var manager = CLLocationManager()

    @Published var currentLocation: CLLocation?
    @Published var loading: Bool = false

    func setup() {
        manager.delegate = self
        updateLocation()
    }

    func updateLocation() {
        if manager.authorizationStatus == .authorizedWhenInUse || manager.authorizationStatus == .authorizedAlways {
            loading = true
            manager.requestLocation()
        }
    }
}

extension LocationManager: CLLocationManagerDelegate {
    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
        updateLocation()
    }

    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
        currentLocation = locations.first
        loading = false
    }

    func locationManager(_ manager: CLLocationManager, didFailWithError error: any Error) {}
}
```

### Step 4: Get the Feedback ID from 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](#closing-the-feedback-loop).

```swift
VoiceFeedbackView(
    sessionObserver: mapGptSession
) {
    showFeedbackAgentSheet = false
} completion: { result in
    showFeedbackAgentSheet = false
    // Note: Result<VoiceFeedbackItem, Error> will contain the feedback ID and automatic-speech recognition text of the report.
    switch result {
    case .success(let feedbackItem):
        sessionStatusDescription = "Succeeded reporting \(feedbackItem.id)"
    case .failure(let error):
        sessionStatusDescription = "Failed to report feedback due to \(error)"
    }
}
```

### Step 5: Add a microphone usage description

Your Info.plist will need to have a `NSMicrophoneUsageDescription` key value pair to explain all the ways that your application uses the microphone including for Feedback Agent.

## How to Send Test Items

When testing the Feedback Agent, it's important to understand how test items are handled to make sure they're properly identified and don't interfere with real feedback. Only production items are reviewed and validated by the Mapbox team. When using any production endpoint for testing, test reports are identified based on the content of the feedback:

-   If your feedback contains phrases like "test feedback" or "test report" (case-insensitive), the system will prefix your feedback with "This is a test feedback."
-   The feedback will still be categorized normally based on its content

```
Example:

User feedback: "I'm sending a test report about a road closure in front of me"

Classification: `road_closure_issue`

Feedback Description: "This is a test feedback. I'm sending a test report about a road closure in front of me"
```

## Feedback Explorer

The [Feedback Explorer](https://console.mapbox.com/feedback-explorer/) inside the Mapbox Console is the easiest mechanism to visualize the items from the users in your application:

![Mapbox Feedback Explorer Items List](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-overview-feedback-explorer-list.91eebb4.480.png)

Tapping on a feedback item will give you all the details, including a map with the location of the report:

![Mapbox Feedback Explorer Item](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-overview-feedback-explorer.4683560.480.jpg)

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](https://www.mapbox.com/forms/voice-feedback-agent).

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

1.  Get the `feedbackId` from the Feedback SDK. This is a unique identifier string automatically generated by the Feedback SDK.
2.  Store this value in your system associated with a specific logged-in user in your app.
3.  Use the [Mapbox Feedback API](#feedback-api) to query the status of the item using its `feedbackId`.
4.  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](https://docs.mapbox.com/api/feedback/) 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.

## Language Support

During the Public Preview, Feedback Agent supports the following languages:

-   English (en-US)
-   German (de-DE)
-   Spanish (es-ES)
-   Japanese (ja-JP)

Other languages and locales are accepted, but recognition accuracy and classification quality may vary. If your use case requires support for languages not in this list, [contact us](https://www.mapbox.com/contact).

## 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](https://www.mapbox.com/contact).