### Install Application on Real Device

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Provide the path to a local APK file for installation. For remote apps or archives, use a URL.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:platformVersion": "<Android_Version>",
  "appium:udid": "<Phone_ID>",
  "appium:app": "/path/to/local/package.apk"
}
```

```json
  "appium:app": "https://example.com/package.apk"
  "appium:app": "https://example.com/package.zip"
```

--------------------------------

### mobile: startScreenStreaming

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts device screen broadcast by creating an MJPEG server. This command requires specific server-side configurations and GStreamer installation.

```APIDOC
## mobile: startScreenStreaming

### Description
Starts device screen broadcast by creating MJPEG server. Multiple calls to this method have no effect unless the previous streaming session is stopped. This method only works if the `adb_screen_streaming` feature is enabled on the server side. It is also required that [GStreamer](https://gstreamer.freedesktop.org/) with `gst-plugins-base`, `gst-plugins-good` and `gst-plugins-bad` packages are installed and available in PATH on the server machine. For the built-in device MJPEG stream (no GStreamer on host), see the [MJPEG guide](docs/mjpeg.md).

### Method
POST

### Endpoint
/session/:sessionId/appium/start_screen_streaming

### Parameters
#### Request Body
- **width** (number) - Optional - The scaled width of the device's screen. If unset then the script will assign it to the actual screen width measured in pixels.
- **height** (number) - Optional - The scaled height of the device's screen. If unset then the script will assign it to the actual screen height measured in pixels.
- **bitRate** (number) - Optional - The video bit rate for the video, in bits per second. The default value is 4000000 (4 Mb/s).
- **host** (string) - Optional - The IP address/host name to start the MJPEG server on. You can set it to `0.0.0.0` to trigger the broadcast on all available network interfaces. `127.0.0.1` by default.
- **pathname** (string) - Optional - The HTTP request path the MJPEG server should be available on. If unset then any pathname on the given `host`/`port` combination will work. Note that the value should always start with a single slash: `/`.
- **tcpPort** (number) - Optional - The port number to start the internal TCP MJPEG broadcast on. This type of broadcast always starts on the loopback interface (`127.0.0.1`). `8094` by default.
- **port** (number) - Optional - The port number to start the MJPEG server on. `8093` by default.
- **quality** (number) - Optional - The quality value for the streamed JPEG images. This number should be in range [1, 100], where 100 is the best quality. `70` by default.
- **considerRotation** (boolean) - Optional - If set to `true` then GStreamer pipeline will increase the dimensions of the resulting images to properly fit images in both landscape and portrait orientations. Set it to `true` if the device rotation is not going to be the same during the broadcasting session. `false` by default.
- **logPipelineDetails** (boolean) - Optional - Whether to log GStreamer pipeline events into the standard log output. Might be useful for debugging purposes. `false` by default.
```

--------------------------------

### Run Development Server

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts the development server for the Appium UiAutomator2 driver.

```bash
npm run dev
```

--------------------------------

### Manual Activity Start Command

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/activity-startup.md

This command can be used to manually test if the specified application package and activity name are correct for starting the application. If this command succeeds manually, it should also work for Appium.

```bash
adb shell am start -W -n com.myfixedpackage/.myfixedactivity.MainActivity -S -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -f 0x10200000
```

--------------------------------

### Install .apks bundle via execute script

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-appbundle.md

Use the 'mobile: installApp' execute script command to install an .apks bundle directly onto the device. This is an alternative to setting the 'app' capability during driver initialization.

```ruby
# Ruby
driver.execute_script 'mobile: installApp', {appPath: 'path/to/your.apks'}
```

--------------------------------

### Start Activity with Appium

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Use this script to start an Android activity. It mirrors the functionality of the `am start-activity` shell command and is useful for launching applications or specific activities within them.

```ruby
driver.execute_script 'mobile: startActivity', {
    wait: true,
    stop: true,
    action: 'android.intent.action.MAIN',
    component: 'io.appium.android.apis/io.appium.android.apis.ApiDemos',
    categories: ['android.intent.category.LAUNCHER'],
    flags: '0x10200000'
}
```

--------------------------------

### Install Appium UiAutomator2 Driver

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Installs the necessary package for developing the Appium UiAutomator2 driver.

```bash
npm install appium-uiautomator2-driver
```

--------------------------------

### mobile: installMultipleApks

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Installs applications using the 'install-multiple' option. Supports installing multiple APKs and configuring installation options.

```APIDOC
## mobile: installMultipleApks

### Description
Install applications via `install-multiple` option. Please read more details in the corresponding section of the `adb --help` command output.

### Arguments
#### Path Parameters
- **apks** (Array<string>) - Required - The path to APKs. Each path should be the full path to the apk to be installed, or an URL to a remote location. Example: `['/path/to/local.apk', 'https://github.com/appium/ruby_lib_core/blob/master/test/functional/app/api.apk.zip?raw=true']`
- **options** (object) - Optional - Installation options. If you want enable `-g` option, you could specify that `{grantPermissions: true}`. `allowTestPackages` corresponds `-t`, `useSdcard` corresponds `-s`, `replace` corresponds `-r` (`-r` is enabled by default), `partialInstall` corresponds `-p`. Example: `{grantPermissions: true, partialInstall: true}`
```

--------------------------------

### mobile: installApp

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Installs the given application package to the device under test. Supports various options for installation, including remote URLs, test packages, and permission granting.

```APIDOC
## mobile: installApp

### Description
Installs the given application package to the device under test. It might raise the `INSTALL_FAILED_VERSION_DOWNGRADE` error if the installation was a version downgrade.

### Arguments
#### Path Parameters
- **appPath** (string) - yes - The local .apk(s) path on the server filesystem or a remote url.
- **timeout** (number) - no - The count of milliseconds to wait until the app is installed.. 6000ms by default.
- **allowTestPackages** (boolean) - no - Set to true in order to allow test packages installation. false by default
- **useSdcard** (boolean) - no - Set to true to install the app on sdcard instead of the device memory. false by default
- **grantPermissions** (boolean) - no - Set to true in order to grant all the permissions requested in the application's manifest automatically after the installation is completed under Android 6+. The targetSdkVersion in the application manifest must be greater or equal to 23 and the Android version on the device under test must be greater or equal to Android 6 (API level 23) to grant permissions. Applications whose targetSdkVersion is lower than or equal to 22 must be reisntalled to grant permissions for Android 6+ devices. false by default
- **replace** (boolean) - no - Set it to false if you don't want the application to be upgraded/reinstalled if it is already present on the device, but throw an error instead. true by default
- **checkVersion** (boolean) - no - Set to true, in order to skip the application installation if the device under test has a greater or equal to the application version. It may help to avoid `INSTALL_FAILED_VERSION_DOWNGRADE` error and unnecessary installation.
```

--------------------------------

### Understand Multi-Display Setup

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

List all available displays using `mobile: listDisplays` to understand the device's display configuration, then group windows by their respective display IDs.

```python
# First, list all displays to understand the display structure
displays = driver.execute_script('mobile: listDisplays')
for display in displays:
    print(f"Logical Display ID: {display['id']}")
    print(f"  Name: {display['name']}")
    print(f"  Physical ID: {display['physicalId']}")
    if display.get('virtualId'):
        print(f"  Virtual ID: {display['virtualId']}")
    print(f"  Is default: {display['isDefault']}")
    print(f"  Size: {display['metrics']['widthPixels']}x{display['metrics']['heightPixels']}")

# Group windows by display
windows = driver.execute_script('mobile: listWindows', {})
windows_by_display = {}
for window in windows:
    display_id = window['displayId']
    if display_id not in windows_by_display:
        windows_by_display[display_id] = []
    windows_by_display[display_id].append(window)

print(f"Windows on each display: {windows_by_display}")
```

--------------------------------

### Practical Use Cases

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Illustrates practical applications of `mobile: listWindows` and `mobile: listDisplays` for debugging, identifying system windows, understanding multi-display setups, and finding active/focused windows.

```APIDOC
## Debugging Window Visibility Issues
```python
windows = driver.execute_script('mobile: listWindows', {'filters': {'packageName': 'com.example.myapp'}})
if not windows:
    print("App window not found!")
else:
    print(f"Found {len(windows)} window(s) from the app")
```

## Finding System Windows (like keyboards)
```python
all_windows = driver.execute_script('mobile: listWindows', {})
system_windows = [w for w in all_windows if w['packageName'] and 'android' in w['packageName']]
print(f"Found {len(system_windows)} system windows")
```

## Understanding Multi-Display Setup
```python
# List all displays
displays = driver.execute_script('mobile: listDisplays')
for display in displays:
    print(f"Logical Display ID: {display['id']}")
    print(f"  Name: {display['name']}")
    print(f"  Physical ID: {display['physicalId']}")
    if display.get('virtualId'):
        print(f"  Virtual ID: {display['virtualId']}")
    print(f"  Is default: {display['isDefault']}")
    print(f"  Size: {display['metrics']['widthPixels']}x{display['metrics']['heightPixels']}")

# Group windows by display
windows = driver.execute_script('mobile: listWindows', {})
windows_by_display = {}
for window in windows:
    display_id = window['displayId']
    if display_id not in windows_by_display:
        windows_by_display[display_id] = []
    windows_by_display[display_id].append(window)

print(f"Windows on each display: {windows_by_display}")
```

## Finding Active or Focused Windows
```python
# Find the currently active window
active_windows = driver.execute_script('mobile: listWindows', {'filters': {'isActive': True}})

# Find windows with input focus
focused_windows = driver.execute_script('mobile: listWindows', {'filters': {'isFocused': True}})

# Find the topmost window from your app
app_windows = driver.execute_script('mobile: listWindows', {'filters': {'packageName': 'com.example.myapp'}})
if app_windows:
    topmost = max(app_windows, key=lambda w: w['layer'])
    print(f"Topmost window layer: {topmost['layer']}")
```

## Using Display Information
```python
# Get display information
displays = driver.execute_script('mobile: listDisplays')
```
```

--------------------------------

### mobile: startService

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts the given service intent. This command invokes the `am startservice` or `am start-service` command under the hood.

```APIDOC
## mobile: startService

### Description
Starts the given service intent. Invokes `am startservice` or `am start-service` command under the hood.

### Arguments

#### Path Parameters
- **intent** (string) - Optional - The full name of the service intent to start
- **user** (number or string) - Optional - The user ID for which the service is started. The `current` user id is used by default
- **foreground** (boolean) - Optional - Set it to `true` if your service must be started as a foreground service. The argument only works for Android 8 and above.
- **action** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **uri** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **mimeType** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **identifier** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **categories** (string or Array<string>) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **component** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **package** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **extras** (Array<Array<string>>) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)
- **flags** (string) - Optional - See the documentation for [startActivity extension](#mobile-startactivity)

### Returned Result
The actual stdout of the downstream `am` command.
```

--------------------------------

### startActivity

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts an Android activity with specified parameters. This method allows for detailed configuration of the activity launch, including intents, user, and various flags.

```APIDOC
## POST /session/:sessionId/uiautomator2/startActivity

### Description
Starts an Android activity with specified parameters. This method allows for detailed configuration of the activity launch, including intents, user, and various flags.

### Method
POST

### Endpoint
/session/:sessionId/uiautomator2/startActivity

### Parameters
#### Request Body
- **intent** (string) - Required - The full name of the activity intent to start. Example: `com.some.package.name/.YourActivityClassName`
- **user** (number or string) - Optional - The user ID for which the service is started. The `current` user is used by default. Example: `1006`
- **wait** (boolean) - Optional - Set it to `true` if you want to block the method call until the Activity Manager's process returns the control to the system. Example: `false`
- **stop** (boolean) - Optional - Set it to `true` to force stop the target app before starting the activity. Example: `false`
- **windowingMode** (integer) - Optional - The windowing mode to launch the activity into. Check [WindowConfiguration.java](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/WindowConfiguration.java) for more details on possible windowing modes (constants starting with `WINDOWING_MODE_`). Example: `1`
- **activityType** (integer) - Optional - The activity type to launch the activity as. Check [WindowConfiguration.java](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/WindowConfiguration.java) for more details on possible activity types (constants starting with `ACTIVITY_TYPE_`). Example: `1`
- **action** (string) - Optional - Action name. The actual value for the Activity Manager's `-a` argument. Example: `android.intent.action.MAIN`
- **uri** (string) - Optional - Unified resource identifier. The actual value for the Activity Manager's `-d` argument. Example: `https://appium.io`
- **mimeType** (string) - Optional - Mime type. The actual value for the Activity Manager's `-t` argument. Example: `application/json`
- **identifier** (string) - Optional - Optional identifier. The actual value for the Activity Manager's `-i` argument. Example: `my_identifier`
- **categories** (string or Array&lt;string&gt;) - Optional - One or more category names. The actual value(s) for the Activity Manager's `-c` argument. Example: `android.intent.category.LAUNCHER`
- **component** (string) - Optional - Component name. The actual value for the Activity Manager's `-n` argument. Example: `com.myapp/com.myapp.SplashActivity`
- **package** (string) - Optional - Package name. The actual value for the Activity Manager's `-p` argument. Example: `com.myapp`
- **extras** (Array&lt;Array&lt;string&gt;&gt;) - Optional - Optional intent arguments. Must be represented as an array of arrays, where each subarray item contains two (only in case it no value is required for the given type) or three string items: value type, key (variable name) and the value itself. Supported value types are: `s`: string. Value must be a valid string; `sn`: null. Value is ignored for this type; `z`: boolean. Value must be either `true` or `false`; `i`: integer. Value must be a valid 4-byte integer number; `l`: long. Value must be a valid 8-byte long number; `f`: float: Value must be a valid float number; `u`: uri. Value must be a valid uniform resource identifier string; `cn`: component name. Value must be a valid component name string; `ia`: Integer[]. Value must be a string of comma-separated integers; `ial`: List&lt;Integer&gt;. Value must be a string of comma-separated integers; `la`: Long[]. Value must be a string of comma-separated long numbers; `lal`: List&lt;Long&gt;. Value must be a string of comma-separated long numbers; `fa`: Float[]. Value must be a string of comma-separated float numbers; `fal`: List&lt;Float&gt;. Value must be a string of comma-separated float numbers; `sa`: String[]. Value must be comma-separated strings. To embed a comma into a string escape it using "\,"; `sal`: List&lt;String&gt;. Value must be comma-separated strings. To embed a comma into a string, escape it using "\,". Example: `[['s', 'varName1', 'My String1'], ['s', 'varName2', 'My String2'], ['ia', 'arrName', '1,2,3,4']]`
- **flags** (string) - Optional - Intent startup-specific flags as a hexadecimal string. Check [Intent documentation](https://developer.android.com/reference/android/content/Intent.html) for the list of available flag values (constants starting with `FLAG_ACTIVITY_`). Flag values could be merged using the logical 'or' operation. Example: `0x10200000 is the combination of two flags: 0x10000000 FLAG_ACTIVITY_NEW_TASK | 0x00200000 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED`

### Request Example
```json
{
  "intent": "com.example.app/.MainActivity",
  "extras": [
    ["s", "extra_key", "extra_value"]
  ],
  "flags": "0x10000000"
}
```

### Response
#### Success Response (200)
- **value** (string) - The actual stdout of the downstream `am` command.

#### Response Example
```json
{
  "value": "Activity launched successfully."
}
```
```

--------------------------------

### mobile: installApp

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Installs or upgrades an application on the device.

```APIDOC
## mobile: installApp

### Description
Installs or upgrades an application package onto the device.

### Method
POST

### Endpoint
/session/{sessionid}/appium/device/install_app

### Parameters
#### Request Body
- **appPath** (string) - Required - The path to the application package (e.g., APK file).
- **options** (object) - Optional - Additional options for installation.
  - **checkAppInstallStatus** (boolean) - Optional - If true, checks if the app is already installed before attempting installation.
  - **allowTestPackages** (boolean) - Optional - If true, allows installation of test packages.
  - **useSdCard** (boolean) - Optional - If true, attempts to install the app on the SD card if available.
```

--------------------------------

### Install Application on Emulator

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Specify the emulator name and Android version along with the application path. Remote app URLs are also supported.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:avd": "<Emulator_Name>",
  "appium:platformVersion": "<Android_Version>",
  "appium:app": "/path/to/local/package.apk"
}
```

```json
  "appium:app": "https://example.com/package.apk"
```

--------------------------------

### mobile: listApps

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Retrieves a list of all installed packages on the device.

```APIDOC
## mobile: listApps

### Description
Lists all installed packages on the Android device.

### Method
POST

### Endpoint
/session/{sessionid}/appium/device/apps_list

### Response
#### Success Response (200)
- **value** (array) - A list of installed application package names.
```

--------------------------------

### mobile: startActivity

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts a specific activity within an application.

```APIDOC
## mobile: startActivity

### Description
Starts a specific activity within an application. This is useful for controlling app rotation preferences.

### Method
POST

### Endpoint
/session/{sessionid}/appium/device/start_activity

### Parameters
#### Request Body
- **intent** (string) - Required - The intent string to start the activity (e.g., 'com.example.app/.MainActivity').
- **options** (object) - Optional - Additional options for starting the activity.
  - **stopAppOnReset** (boolean) - Optional - If true, stops the app on reset.
```

--------------------------------

### mobile: startActivity

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts the given activity intent, extending the functionality of the app management API.

```APIDOC
## mobile: startActivity

### Description
Starts the given activity intent. Invokes `am start`/`am start-activity` command under the hood. This method extends the functionality of the [Start Activity](#applications-management) app management API.
```

--------------------------------

### Make bundletool.jar executable

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-appbundle.md

Ensure the bundletool.jar file has execute permissions. Use the chmod command to set the appropriate file permissions, for example, 'chmod 655 /path/to/bundletool.jar'.

```bash
$ chmod 655 /path/to/bundletool.jar
```

--------------------------------

### mobile: isAppInstalled

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Verifies whether an application is installed on the device under test.

```APIDOC
## mobile: isAppInstalled

### Description
Verify whether an application is installed on the device under test.

### Method
POST

### Endpoint
/session/:sessionId/appium/device/app_installed

### Parameters
#### Request Body
- **appId** (string) - yes - The identifier of the application package to be checked.
- **user** (number or string) - no - The user ID for which the package is installed. The `current` user is used by default.

### Response
#### Success Response (200)
True or false
```

--------------------------------

### Schedule Action Example

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md

Schedules an action to periodically fetch page source snapshots. This is useful for detecting and interacting with dynamic UI elements like popups.

```python
driver.execute_script('mobile: scheduleAction', {
  'name': 'myPopupHandlingAction',
  'steps': [{
    'type': 'source',
    'name': 'fetchPageSourceStep',
    'payload': {
      'subtype': 'xml'
    }
  }],
  'intervalMs': 1000,
  'times': 30,
  'maxHistoryItems': 30,
})
```

--------------------------------

### mobile: isAppInstalled

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Checks if a specific application is installed on the device.

```APIDOC
## mobile: isAppInstalled

### Description
Checks if a given application package is installed on the device.

### Method
POST

### Endpoint
/session/{sessionid}/appium/device/app_installed

### Parameters
#### Query Parameters
- **bundleId** (string) - Required - The package name of the application to check.

### Response
#### Success Response (200)
- **value** (boolean) - True if the app is installed, false otherwise.
```

--------------------------------

### Custom Launch on Emulator

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Start a session on an emulator without an app, beginning at the Home screen. This allows for flexible app lifecycle management using Appium's extensions.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:avd": "<Emulator_Name>",
  "appium:platformVersion": "<Android_Version>"
}
```

--------------------------------

### Get Display Information

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Retrieve detailed information about all connected displays on the device using the `mobile: listDisplays` command.

```python
# Get display information using mobile: listDisplays
displays = driver.execute_script('mobile: listDisplays')
```

--------------------------------

### Execute Shell Command via ADB (Java Example)

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Executes a shell command on the device using ADB. This requires the 'uiautomator2:adb_shell' server feature to be enabled. The command and its arguments are provided as parameters.

```java
// Java 11+
var result = driver.executeScript("mobile: shell", Map.ofEntries(
    Map.entry("command", "echo"),
    Map.entry("args", List.of("-f", "/sdcard/myfile.txt")),
    Map.entry("timeout", 100000),
    Map.entry("includeStderr", true)
));
```

--------------------------------

### List All Displays on Device

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Retrieves an array of display information objects for all available displays on the device. Useful for multi-display setups.

```python
# List all displays
displays = driver.execute_script('mobile: listDisplays')

for display in displays:
    print(f"Display ID: {display['id']}")
    print(f"  Name: {display['name']}")
    print(f"  Physical ID: {display['physicalId']}")
    if display.get('virtualId'):
        print(f"  Virtual ID: {display['virtualId']}")
    print(f"  Is default: {display['isDefault']}")
    print(f"  Size: {display['metrics']['widthPixels']}x{display['metrics']['heightPixels']}")
    print(f"  Density: {display['metrics']['density']} ({display['metrics']['densityDpi']} DPI)")
```

--------------------------------

### Custom Launch on Real Device

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Initiate a session on a real device without specifying an app, starting at the Home screen. Subsequent app management can be done via Appium's mobile methods.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:platformVersion": "<Android_Version>",
  "appium:udid": "<Phone_ID>"
}
```

--------------------------------

### Example WebviewsMapping Object

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

This JSON object represents the structure of the result returned by the 'mobile: getContexts' command, detailing information about detected webviews and their associated pages.

```json
{
  "proc": "@webview_devtools_remote_22138",
  "webview": "WEBVIEW_22138",
  "info": {
    "Android-Package": "io.appium.settings",
    "Browser": "Chrome/74.0.3729.185",
    "Protocol-Version": "1.3",
    "User-Agent": "Mozilla/5.0 (Linux; Android 10; Android SDK built for x86 Build/QSR1.190920.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/74.0.3729.185 Mobile Safari/537.36",
    "V8-Version": "7.4.288.28",
    "WebKit-Version": "537.36 (@22955682f94ce09336197bfb8dffea991fa32f0d)",
    "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/browser"
  },
  "pages": [
    {
      "description": "{\"attached\":true,\"empty\":false,\"height\":1458,\"screenX\":0,\"screenY\":336,\"visible\":true,\"width\":1080}",
      "devtoolsFrontendUrl": "http://chrome-devtools-frontend.appspot.com/serve_rev/@22955682f94ce09336197bfb8dffea991fa32f0d/inspector.html?ws=127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F",
      "id": "27325CC50B600D31B233F45E09487B1F",
      "title": "Releases · appium/appium · GitHub",
      "type": "page",
      "url": "https://github.com/appium/appium/releases",
      "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F"
    }
  ],
  "webviewName": "WEBVIEW_com.io.appium.setting"
}
```

--------------------------------

### List All Available Displays and Their IDs

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Use `mobile: listDisplays` to get a comprehensive list of all available displays, including their logical, physical, and virtual IDs, along with display metrics and default status.

```python
# 1. List displays to see all available displays with their IDs
displays = driver.execute_script('mobile: listDisplays')
for display in displays:
    print(f"Logical Display ID: {display['id']}")
    print(f"  Physical ID: {display['physicalId']}")
    if display.get('virtualId'):
        print(f"  Virtual ID: {display['virtualId']}")
    print(f"  Is default: {display['isDefault']}")
    print(f"  Size: {display['metrics']['widthPixels']}x{display['metrics']['heightPixels']}")
```

--------------------------------

### mobile: deepLink

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts a URI to navigate directly to specific content within an application. This command is useful for testing deep linking functionality.

```APIDOC
## mobile: deepLink

### Description
Start URI that may take users directly to the specific content in the app. Read [Reliably Opening Deep Links Across Platforms and Devices](https://appiumpro.com/editions/84-reliably-opening-deep-links-across-platforms-and-devices) for more details.

### Arguments

#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **url** (string) - Required - The URL to start.
- **package** (string) - Optional - The name of the package to start the URI with. This argument was required previously but became optional since version 3.9.3.
- **waitForLaunch** (boolean) - Optional - If `false` then ADB won't wait for the started activity to return the control. `true` by default.

### Request Example
```json
{
  "url": "theapp://login/",
  "package": "com.mycompany",
  "waitForLaunch": false
}
```

### Response
#### Success Response (200)
- **value** (any) - The result of the deep link operation.

#### Response Example
```json
{
  "value": null
}
```
```

--------------------------------

### App Capabilities

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Capabilities to configure application behavior during test sessions, such as waiting for specific activities or packages, setting installation timeouts, and controlling app launch and termination.

```APIDOC
## App Capabilities

### Description
Capabilities to configure application behavior during test sessions, such as waiting for specific activities or packages, setting installation timeouts, and controlling app launch and termination.

### Capabilities

- **appium:appWaitActivity** (string) - Identifier of the first activity that the application invokes. If not provided then equals to `appium:appActivity`. Read [How To Troubleshoot Activities Startup](docs/activity-startup.md) for more details.
- **appium:appWaitPackage** (string) - Identifier of the first package that is invoked first. If not provided then equals to `appium:appPackage`. Read [How To Troubleshoot Activities Startup](docs/activity-startup.md) for more details.
- **appium:appWaitDuration** (number) - Maximum amount of milliseconds to wait until the application under test is started (e. g. an activity returns the control to the caller). `20000` ms by default. Read [How To Troubleshoot Activities Startup](docs/activity-startup.md) for more details.
- **appium:androidInstallTimeout** (number) - Maximum amount of milliseconds to wait until the application under test is installed. `90000` ms by default.
- **appium:appWaitForLaunch** (boolean) - Whether to block until the app under test returns the control to the caller after its activity has been started by Activity Manager (`true`, the default value) or to continue the test without waiting for that (`false`).
- **appium:intentCategory** (string) - Set an optional intent category to be applied when starting the given appActivity by [Activity Manager](https://developer.android.com/studio/command-line/adb#am). Defaults to `android.intent.category.LAUNCHER`. Please use [mobile:startActivity](#mobile-startactivity) in case you don't set an explicit value.
- **appium:intentAction** (string) - Set an optional intent action to be applied when starting the given appActivity by [Activity Manager](https://developer.android.com/studio/command-line/adb#am). Dfaults to `android.intent.action.MAIN`. Please use [mobile:startActivity](#mobile-startactivity) in case you don't set an explicit value.
- **appium:intentFlags** (string) - Set an optional intent flags to be applied when starting the given appActivity by [Activity Manager](https://developer.android.com/studio/command-line/adb#am). Defaults to `0x10200000` (FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_RESET_TASK_IF_NEEDED flags). Please use [mobile:startActivity](#mobile-startactivity) in case you don't set an explicit value.
- **appium:optionalIntentArguments** (string) - Set an optional intent arguments to be applied when starting the given appActivity by [Activity Manager](https://developer.android.com/studio/command-line/adb#am).
- **appium:dontStopAppOnReset** (boolean) - Set it to `true` if you don't want the application to be restarted if it was already running. If `appium:noReset` is falsy, then the app under test is going to be restarted if either this capability is falsy (the default behavior) or `appium:forceAppLaunch` is set to `true`. `false` by default.
- **appium:forceAppLaunch** (boolean) - Set it to `true` if you want the application under test to be always forcefully restarted on session startup even if `appium:noReset` is `true`, and the app was already running. If `noReset` is falsy, then the app under test is going to be restarted if either this capability set to `true` or `appium:dontStopAppOnReset` is falsy (the default behavior). `false` by default. Available since driver version 2.12.
- **appium:shouldTerminateApp** (boolean) - Set it to `true` if you want the application under test to be always terminated on session end even if `appium:noReset` is `true`. If `noReset` is falsy, then the app under test is going to be terminated if `appium:dontStopAppOnReset` is also falsy (the default behavior). `false` by default.
- **appium:autoLaunch** (boolean) - Whether to launch the application under test automatically (`true`, the default value) after a test starts.
- **appium:autoGrantPermissions** (boolean) - Whether to grant all the requested application permissions automatically when a test starts(`true`). The targetSdkVersion in the application manifest must be greater or equal to 23 and the Android version on the device under test must be greater or equal to Android 6 (API level 23) to grant permissions. Applications whose targetSdkVersion is lower than or equal to 22 must be reinstalled to grant permissions, for example, by setting the `appium:fullReset` capability as `true` for Android 6+ devices. If your app needs some special security permissions, like access to notifications or media recording, consider using [mobile: changePermissions](#mobile-changepermissions) extension with `appops` target. `false` by default.
- **appium:otherApps** (string) - Allows to set one or more comma-separated paths to Android packages that are going to be installed along with the main application under test. This may be useful if the tested app has dependencies.
- **appium:uninstallOtherPackages** (string) - Allows to set one or more comma-separated package identifiers to be uninstalled from the device before a test starts.
- **appium:allowTestPackages** (boolean) - If set to `true` then it would be possible to use packages built with the test flag for the automated testing (literally adds `-t` flag to the `adb install` command). `false` by default.
```

--------------------------------

### mobile: listApps

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Lists all installed packages on the Android device, optionally filtered by user. An exception will be thrown on devices running Android API below level 26.

```APIDOC
## mobile: listApps

### Description
Lists all installed packages on the Android device, optionally filtered by user. An exception will be thrown on devices running Android API below level 26.

### Method
POST

### Endpoint
/session/:sessionId/appium/device/list_apps

### Parameters
#### Request Body
- **user** (number or string) - no - The user ID for which the package is installed. The `current` user is used by default.

### Response
#### Success Response (200)
A map where keys are packageName and values are maps of platform-specific app properties since UIAutomator2 driver v7.0.0. UIAutomator2 driver v6.9.0 and v6.9.1 were a list of installed package names.
```

--------------------------------

### mobile: startLogsBroadcast

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Starts an Android logcat broadcast websocket on the Appium server. Connected listeners will receive logcat log lines in real-time.

```APIDOC
## mobile: startLogsBroadcast

### Description
Starts Android logcat broadcast websocket on the same host and port where Appium server is running at `/ws/session/:sessionId:/appium/device/logcat` endpoint. The method will return immediately if the web socket is already listening. Each connected websocket listener will receive logcat log lines as soon as they are visible to Appium. Read [Using Mobile Execution Commands to Continuously Stream Device Logs with Appium](https://appiumpro.com/editions/55-using-mobile-execution-commands-to-continuously-stream-device-logs-with-appium) for more details.

Consider using [logs broadcast via BiDi](./docs/bidi.md#logentryadded) over this extension.

### Arguments

#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```json
{
  "command": "mobile: startLogsBroadcast"
}
```

### Response
#### Success Response (200)
- **value** (any) - The result of starting the log broadcast.

#### Response Example
```json
{
  "value": null
}
```
```

--------------------------------

### Get Display Information using mobile: listDisplays

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Retrieve a list of all available physical and virtual displays on the device using the `mobile: listDisplays` script. This information is recommended for identifying specific display IDs before capturing screenshots.

```python
# Get display ID from mobile: listDisplays (recommended)
displays = driver.execute_script('mobile: listDisplays')
```

--------------------------------

### mobile: removeApp

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Removes the corresponding application if it is installed. The call is ignored if the app is not installed.

```APIDOC
## mobile: removeApp

### Description
Remove the corresponding application if is installed. The call is ignored if the app is not installed.

### Method
POST

### Endpoint
/session/:sessionId/appium/device/remove_app

### Parameters
#### Request Body
- **appId** (string) - yes - The identifier of the application package to be removed.
- **timeout** (number) - no - The count of milliseconds to wait until the app is terminated. 20000ms by default.
- **keepData** (boolean) - no - Set to true in order to keep the application data and cache folders after uninstall.

### Response
#### Success Response (200)
True is the app has been found on the device and successfully removed. Otherwise false.
```

--------------------------------

### Listing Windows with Filters

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Demonstrates how to use the `mobile: listWindows` command with different filter options to find specific windows.

```APIDOC
## Find windows from a specific package
```python
windows = driver.execute_script('mobile: listWindows', {
    'filters': {
        'packageName': 'com.example.myapp'
    }
})
```

## Find windows on a specific display
```python
windows = driver.execute_script('mobile: listWindows', {
    'filters': {
        'displayId': 0
    }
})
```

## Find windows by physical display ID
```python
windows = driver.execute_script('mobile: listWindows', {
    'filters': {
        'physicalDisplayId': '1234567890'
    }
})
```

## Find a specific window by ID
```python
windows = driver.execute_script('mobile: listWindows', {
    'filters': {
        'windowId': 42
    }
})
```

## Combine multiple filters (AND logic)
```python
windows = driver.execute_script('mobile: listWindows', {
    'filters': {
        'packageName': 'com.example.myapp',
        'displayId': 0
    }
})
```
```

--------------------------------

### Launch Pre-Installed App on Real Device

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Use `appPackage` and `appActivity` to launch an existing app. Set `noReset` to `true` to prevent resetting the app's state.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:platformVersion": "<Android_Version>",
  "appium:udid": "<Phone_ID>",
  "appium:appPackage": "<App_Package_Id>",
  "appium:appActivity": "<App_Activity_Id>",
  "appium:noReset": true
}
```

--------------------------------

### Skip Chromedriver Download on Install

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

For UIA2 driver versions below 3.8.0, set the APPIUM_SKIP_CHROMEDRIVER_INSTALL environment variable to skip the automated download of Chromedriver during driver installation.

```bash
APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2
```

--------------------------------

### Launch Pre-Installed App on Emulator

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/capability-sets.md

Configure capabilities to launch a pre-installed application on an emulator using its package and activity IDs. `noReset` ensures the app state is preserved.

```json
{
  "platformName": "Android",
  "appium:automationName": "uiautomator2",
  "appium:avd": "<Emulator_Name>",
  "appium:platformVersion": "<Android_Version>",
  "appium:appPackage": "<App_Package_Id>",
  "appium:appActivity": "<App_Activity_Id>",
  "appium:noReset": true
}
```

--------------------------------

### Install Driver with Specific Chromedriver Version

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Installs the UIA2 driver while specifying a particular Chromedriver version using an environment variable. This method is applicable for driver versions below 3.8.0.

```bash
CHROMEDRIVER_VERSION=2.20 appium install driver uiautomator2
```

--------------------------------

### List All Windows with `mobile: listWindows`

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

Use this command to retrieve information about all available windows on the device. This is crucial for understanding the window structure in multi-window scenarios. The output includes window IDs, display information, package names, types, titles, layers, focus states, and bounds.

```python
# List all windows without filters
windows = driver.execute_script('mobile: listWindows')

# Print information about each window
for window in windows:
    print(f"Window ID: {window['windowId']}")
    print(f"Display ID: {window['displayId']}")
    print(f"Physical Display ID: {window['physicalDisplayId']}")
    if window.get('virtualDisplayId'):
        print(f"Virtual Display ID: {window['virtualDisplayId']}")
    print(f"Package: {window['packageName']}")
    print(f"Type: {window['type']}")
    print(f"Title: {window['title']}")
    print(f"Layer: {window['layer']}")
    print(f"Active: {window['isActive']}, Focused: {window['isFocused']}")
    print(f"Bounds: {window['rect']}")
    print("---")
```

--------------------------------

### GET /session/:sessionId/context

Source: https://github.com/appium/appium-uiautomator2-driver/blob/master/README.md

Retrieves the name of the current context.

```APIDOC
## GET /session/:sessionId/context

### Description
Retrieves the name of the current context.

### Method
GET

### Endpoint
/session/:sessionId/context

### Response
#### Success Response (200)
- **name** (string) - The name of the current context.

#### Response Example
{
  "name": "NATIVE_APP"
}
```