# Retrieve feedback from apps

Some apps are capable of sending feedback to EMMs in the form of **keyed app
states** . A keyed app state is made up of a unique identifier (key),
corresponding message (optional), machine-readable data (optional), severity
status, and timestamp. To send them, an app needs to integrate with the
[Enterprise Jetpack library](https://developer.android.com/reference/androidx/enterprise/feedback/package-summary).

As an EMM, you can use the data from keyed app states to keep IT admins
up-to-date with the apps installed on managed devices and profiles. An example
of how this might work is described in [Display feedback to enterprises](https://developers.google.com/android/work/play/emm-api/app-feedback#display_app_feedback_to_enterprises).

## Enable device reports

Apps send keyed app states on a per-device basis. Before any keyed app states
are accepted from any of the apps on the device, you need to enable the device
reports for a device. Until the policy is updated on the device, any keyed app
states are ignored and lost forever. Enable device reports **before**
completing device enrollment, as early as possible in the enrollment
process. This ensures that you receive app feedback generated during device
enrollment and that no keyed app states are lost.

- Call [`devices.update()`](https://developers.google.com/android/work/play/emm-api/v1/devices/update), setting `policy.deviceReportPolicy` to `"deviceReportEnabled"`.

## Retrieve device reports

There are several ways to retrieve a device report:

- To retrieve device reports along with other notifications, call [`enterprises.pullNotificationSet()`](https://developers.google.com/android/work/play/emm-api/v1/enterprises/pullNotificationSet). In the response, each `deviceReportUpdateEvent` denotes a device report.
- To retrieve a device report updated with the latest keyed app states for a specified device, call [`devices.get()`](https://developers.google.com/android/work/play/emm-api/v1/devices/get).
- To force a device to upload the latest app states, call [`devices.forceReportUpload()`](https://developers.google.com/android/work/play/emm-api/v1/devices/forceReportUpload). This method uploads a report containing any changes in app states on the device since the last report was generated.

> [!NOTE]
> **Note:** You can call [`devices.forceReportUpload()`](https://developers.google.com/android/work/play/emm-api/v1/devices/forceReportUpload) up to three times every 24 hours for a given device. Typically, the device uploads app feedback at least once per day. Calling `devices.forceReportUpload()` triggers the device to upload app feedback as soon as possible. The device requires connectivity to ensure timely app feedback delivery. Keep in mind that method uses time, data, and battery on the device. Therefore, limit your usage of this method to infrequent actions that require timely delivery of app feedback.

## View keyed app states

Device reports are a part of device resources. Reports include an `appState`
object for each app (package) installed on the device or in its work profile.
Keyed app states (`keyedAppState`) for a given package are listed in
`appState` object, like in the example below:

    {
       "result":{
          "kind":"androidenterprise#device",
          "report":{
             "appState":[
                {
                   "keyedAppState":[
                      {
                         "severity":"severityError",
                         "data":"user",
                         "message":"Username or password are incorrect",
                         "key":"account",
                         "stateTimestampMillis":"1556206406926"
                      }
                   ],
                   "packageName":"com.google.android.feedbacktestapp"
                }
             ],
             "lastUpdatedTimestampMillis":"1556206407685"
          },
          "androidId":"32714368a0ad8ad5",
          "managementType":"managedProfile",
          "policy":{
             "deviceReportPolicy":"deviceReportEnabled"
          }
       }
    }

Each keyed app states contains the following:

| Field | Description |
|---|---|
| `key` | The unique key identifying the state. |
| `severity` | The severity of the state: `INFO` indicates an informative message. For example if a managed configuration is set successfully. `ERROR` indicates the enterprise needs to take action to correct a problem. For example, if a managed configuration failed to set. |
| `message` | An optional string providing details about the app state. App developers are advised to treat this field as a user-facing message. |
| `data` | An optional string providing computer-readable details to EMMs about the app state. For example, a value that an IT admin could query against in your console, such as "notify me if the battery_warning data \< 10". |
| `stateTimestampMillis` | The timestamp (in milliseconds) indicating when the app state was last updated on the device. |
| `lastUpdatedTimestampMillis` | The timestamp (in milliseconds) indicating when the device last uploaded keyed app states. |

## Display app feedback to enterprises

Apps can send feedback for a variety of reasons. However, the most common use
case for sending keyed app states is to provide feedback about managed
configurations. For example:

1. An IT admin uses your EMM console to [set managed configurations](https://developers.google.com/android/work/play/emm-api/managed-configurations#specify_managed_configurations) for an app.
2. In the backend, you [send the configurations to the app](https://developers.google.com/android/work/play/emm-api/managed-configurations#apply_managed_configurations).
3. The app attempts to apply the configurations. For each configuration, the app sends a keyed app state indicating its status (for example, a confirmation message or error notification).
4. To view these keyed app states, you [retrieve a device report](https://developers.google.com/android/work/play/emm-api/app-feedback#retrieve_device_reports).
5. Using information from the keyed app states, your EMM console displays the status of the managed configurations in a user-friendly way.

### Alert IT admins to errors

A keyed app state with severity `ERROR` indicates the organization needs to take
action in order to correct a problem. EMMs should **always** alert organizations
to errors, either through their EMM console or other means. For example, your
EMM console could display an error dashboard that links to the feedback for a
given device with errors.

If an error state is corrected, the app send a follow-up state with the same key
as the original error state and an updated severity of `INFO`. EMMs should
**always** inform organizations as soon as an error is corrected. For example,
remove the error from your console's error dashboard or mark it as resolved.

> [!IMPORTANT]
> **Tip:** Add support for IT admins to mute a specific error in case an app fails to correctly update an error state after the error is resolved.