# Command (/docs/settings/mqtt/topics/command)



## 1. Settings [#1-settings]

### 1.1. Topic Name [#11-topic-name]

All [global variables](/docs/settings/mqtt/#3-global-variables) are supported.
For example,

```js
wk/${USERNAME}/${APP_INSTANCE_ID}/command
```

**Default:**

```js
wk/command
```

### 1.2. Quality of Service (QoS) [#12-quality-of-service-qos]

Quality of Service (QoS) ensures different message delivery guarantees
in case of connection failures.

**Default:** At Most Once (0)

### 1.3. Retain Handling [#13-retain-handling]

Control whether Webview Kiosk should receive existing
retained messages when subscribing.

**Default:** Do Not Send (2)

### 1.4. Retain as Published [#14-retain-as-published]

Controls whether retained messages from the broker keep their original
retained flag when delivered to the subscriber.

**Default:** false

## 2. Payloads [#2-payloads]

In addition to the
[Shared Subscribe Payload Properties](/docs/settings/mqtt/topics/#3-shared-subscribe-payload-properties),
the following properties exists for all commands:

<table>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>command</code>
      </td>

      <td>
        string
      </td>

      <td>
        The command to execute, e.g. 

        <code>clear_history</code>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>interact</code>
      </td>

      <td>
        boolean 

        <em>(optional)</em>
      </td>

      <td>
        Whether a user interaction should be triggered.

        For example, this will restore brightness if <code>Web Lifecycle → Dim Screen on Inactivity (seconds)</code> is configured.

        <strong>Default:</strong> true
      </td>
    </tr>

    <tr>
      <td>
        <code>wakeScreen</code>
      </td>

      <td>
        boolean 

        <em>(optional)</em>
      </td>

      <td>
        Whether to wake the screen if it is turned off.

        This requires <code>Settings → MQTT → Use Foreground Service</code>.

        It is highly recommended that you disable battery optimisation for
        Webview Kiosk, which will help keep its foreground service alive.

        For more details, visit

        * [https://dontkillmyapp.com](https://dontkillmyapp.com)

        <strong>Default:</strong> false
      </td>
    </tr>
  </tbody>
</table>

### 2.1. Go Back [#21-go-back]

Navigates one page back in history.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "go_back"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "go_back",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.2. Go Forward [#22-go-forward]

Navigates one page forward in history.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "go_forward"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "go_forward",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.3. Go Home [#23-go-home]

Navigates to your configured home page.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "go_home"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "go_home",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.4. Refresh [#24-refresh]

Refresh the current webview page.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "refresh"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "refresh",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.5. Go to URL [#25-go-to-url]

Navigates to a specific URL.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "go_to_url",
      "data": {
        "url": "https://webviewkiosk.nktnet.uk"
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "go_to_url",
      "data": {
        "url": "https://webviewkiosk.nktnet.uk"
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.6. Search [#26-search]

Perform a query search using the selected search engine. This
is the same as using Webview Kiosk's address bar.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "search",
      "data": {
        "query": "How to Train Your Dragon"
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "search",
      "data": {
        "query": "How to Train Your Dragon"
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.7. Clear History [#27-clear-history]

Removes the navigation history, leaving the current URL
as the only entry in the stack.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "clear_history"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "clear_history",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.8. Toast [#28-toast]

Shows a short toast message.

If the message is empty or only contains white space, no toast will be shown.
This is still helpful if you need a dummy command to:

* trigger a user interaction with the `interact` property
* turn the screen on with the `wakeScreen` property

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "toast",
      "data": {
        "message": "Welcome!"
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "toast",
      "data": {
        "message": "Welcome!"
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.9. Lock [#29-lock]

Start lock task mode (or screen pinning) depending on whether Webview Kiosk has
device owner permissions.

Please note that for screen pinning, the user will be prompted to confirm the
action, which needs to be done on the device.

If possible, we recommend to always enable lock task packages for Webview Kiosk -
more details in the [security](/docs/security) section.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "lock"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "lock",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.10. Unlock [#210-unlock]

Stop lock task mode (or screen pinning) depending on whether Webview Kiosk has
device owner permissions.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "unlock"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "unlock",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.11. Reconnect [#211-reconnect]

Disconnect, then reconnect and resubscribe to all MQTT topics.

This is helpful if you have updated any MQTT-related settings, which
requires a reconnection to apply.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "reconnect"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "reconnect",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.12. Lock Device [#212-lock-device]

Turns the device screen off.

This command requires device owner privileges or Dhizuku permission. For more
details, see the [security](/docs/security#33-device-owner-mode) documentation.

Note that if the `MQTT → Use Foreground Service` setting is not enabled,
locking the device will also stop the MQTT connection.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "lock_device"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "lock_device",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.13. Page Up [#213-page-up]

Scrolls the contents of this WebView up by half the view size.

You can also specify `absolute: true` in the payload's data property
to scroll fully up the page.

This command uses the
[Webview#pageDown](https://developer.android.com/reference/android/webkit/WebView#pageDown\(boolean\))
API.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "page_up"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "page_up",
      "data": {
        "absolute": true
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.14. Page Down [#214-page-down]

Scrolls the contents of this WebView down by half the page size.

You can also specify `absolute: true` in the payload's data property
to scroll fully down the page.

This command uses the
[Webview#pageUp](https://developer.android.com/reference/android/webkit/WebView#pageUp\(boolean\))
API.

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "page_down"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "page_down",
      "data": {
        "absolute": true
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.15. Notify [#215-notify]

Shows a notification on the device.

The title comes from the most recent message, and the body will display the
content text of the last 5 messages.

This feature requires:

* Android `POST_NOTIFICATIONS` permission
* `Settings -> Device -> Allow Notifications`

Additionally, when in kiosk/locked mode, the following are required:

* Device owner or Dhizuku privileges
* `Settings -> Device -> Device Owner -> Home`
* `Settings -> Device -> Device Owner -> Notifications`

Your payload data value can have the following properties:

| Property       | Type     | Default   | Description                                                                                                                                                       |
| -------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentTitle` | string?  | `MQTT`    | The title of the notification.                                                                                                                                    |
| `contentText`  | string   | `Notify`  | The content body of the notification.                                                                                                                             |
| `silent`       | boolean? | `false`   | If `true`, the notification will not make sound or vibration.                                                                                                     |
| `onGoing`      | boolean? | `false`   | See [NotificationCompat.Builder#setOngoing(boolean)](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder#setOngoing\(boolean\)). |
| `priority`     | string?  | `DEFAULT` | Notification priority: `MIN`, `LOW`, `DEFAULT`, `HIGH`, or `MAX`.                                                                                                 |
| `timeout`      | long?    | `0`       | Time in milliseconds before auto-dismiss (0 = no timeout).                                                                                                        |
| `autoCancel`   | boolean? | `true`    | Dismiss the notification when the user taps it.                                                                                                                   |

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "notify",
      "data": {
        "contentText": "Hello, World!"
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "notify",
      "data": {
        "contentTitle": "MQTT",
        "contentText": "Hello, World!",
        "silent": true,
        "onGoing": false,
        "priority": "DEFAULT",
        "timeout": 5000,
        "autoCancel": true
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": true,
      "wakeScreen": false
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.16. Launch Package [#216-launch-package]

Open an application based on its package name, e.g. `com.afwsamples.testdpc`.

In Lock Task Mode, the same restrictions outlined in [Web Browsing](/docs/settings/web-browsing)
under `Kiosk Control Panel Actions -> Apps` applies.

Additionally, packages can only be launched when Webview Kiosk is in the foreground, unless
direct Device Owner permission has been granted. Dhizuku is insufficient.

In the payload `data`, you can optionally specify the `activityName`. For example, this can
be any of the following:

* `com.afwsamples.testdpc.PolicyManagementActivity`
* `.PolicyManagementActivity`
* `PolicyManagementActivity`

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "launch_package",
      "data": {
        "packageName": "com.afwsamples.testdpc"
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "launch_package",
      "data": {
        "packageName": "com.afwsamples.testdpc",
        "activityName": ".PolicyManagementActivity"
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.17. Clear Cache [#217-clear-cache]

Clears webview cache.  This is equivalent to [Clear Cache Action](/docs/setting-actions/#43-clear-actions).

Example Payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "command": "clear_cache"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```json
    {
      "command": "clear_cache",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],
      "interact": false,
      "wakeScreen": true
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>