# showApp

Command (Application).

Starts the application in the foreground

Brings BeNav to the front. A client application that has sent BeNav a route, a message or a set of
POIs uses this when the driver needs to actually look at the map, so the hand-off from one
application to the other happens without asking the driver to find and tap an icon.

BeNav is a separate application on the device, so this is the seam between the two. The client
application decides *when* the driver should be looking at navigation;
`showApp` makes it so.

**Worth knowing**

- It cannot start a stopped application. Android forbids a background broadcast from launching an
  activity, so a command sent while BeNav is down is refused with
  `-7 application.not.started`. BeNav has to be launched first, from its own icon, or by
  sending the command as an Activity intent.
- Bringing BeNav forward from the background requires the "Display over other apps"
  permission on Android 10 and later. Without it the command returns
  `21 start.activity.exception`.

**Example: a two-application workflow**

A field-service application manages the day's jobs. When the technician accepts one, the
application sends [`startGuidance`](https://docs.benomad.com/benav-rnc/commands/start-guidance.md) followed by `showApp`: BeNav comes to the
front already routed to the site, and the technician simply drives. On arrival,
[`onDestinationReached`](https://docs.benomad.com/benav-rnc/notifications/on-destination-reached.md) tells the field-service application to take the screen back for the
job sheet.

## Command

```
{
  "jsonrpc": "2.0",
  "method": "showApp",
  "id": "1"
}
```

## Response

### Success

```
{
  "jsonrpc": "2.0",
  "result": {},
  "id": "1"
}
```

### Error

Generic errors, plus:

- `-7 application.not.started` - the application was not running.
- `21 start.activity.exception` - the application is running in the background but could not be brought to the front. On Android 10+ this needs "Display over other apps" (`SYSTEM_ALERT_WINDOW`) to be granted to BeNav.