Niaozun WebSocket API Documentation
After starting the Niaozun PC client, the WebSocket API becomes available. Listening port: 33332WebSocket Address：
ws://127.0.0.1:33332/Content‑Type:application/json
Get User Info
Get logged‑in user information.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; the identical ID will be returned in response | No |
| type | String | Fixed value: getUserinfo | Yes |
Request Example
{"id":"abc123456","type":"getUserinfo"}Response Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| state | int | 0=Success, Non‑0=Failure | Yes |
| message | String | Error hint message | Yes |
| data | JSON | User data example: {"UserAccount":"user_account","id":"3"} | Yes |
Response Example
{"id":"abc123456","state":0,"message":"","data":{"UserAccount":"user_account","id":"3"}}Get Device List
Fetch connected device address list.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: list | Yes |
Request Example
{"id":"abc123456","type":"list"}Response Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| state | int | 0=Success, Non‑0=Failure | Yes |
| message | String | Error hint message | Yes |
| data | JSON Array | Device address array e.g. ["172.16.0.53:5555","172.16.0.180:5555"] | Yes |
Response Example
{"id":"abc123456","state":0,"message":"","data":["172.16.0.53:5555","172.16.0.180:5555"]}Get Screen Screenshot
Obtain the latest screen frame from target devices.
Tips: Base64 returned does not include the
data:image/jpeg;base64,prefix.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: getscreen | Yes |
| serial | Array | Device serial numbers. Empty array [] = all devices; single ["qeh8ea1s"]; multiple ["qeh8ea1s","r515aaa"]. Get serial via dedicated interface. | Yes |
| action | int | 0=Return base64 screenshot1=Save screenshot to local disk2=Return original‑quality base643=Save original‑quality image to disk | Yes |
| data | JSON | Object containing path and crop coordinates | Yes |
| └‑ path | String | Local disk save directory e.g. D:\\11111\\ | Yes |
| └‑ x | int | Crop start X coordinate | No |
| └‑ y | int | Crop start Y coordinate | No |
| └‑ w | int | Crop width | No |
| └‑ h | int | Crop height | No |
Request Examples
- Return compressed base64 image
{"id":"abc123456","type":"getscreen","serial":[],"action":0,"data":{"path":"D:\\11111\\"}}- Save compressed image to local disk
{"id":"abc123456","type":"getscreen","serial":[],"action":1,"data":{"path":"D:\\11111\\"}}- Return original‑quality base64
{"id":"abc123456","type":"getscreen","serial":[],"action":2,"data":{"path":"D:\\11111\\"}}- Save original‑quality image to local disk
{"id":"abc123456","type":"getscreen","serial":[],"action":3,"data":{"path":"D:\\11111\\"}}Response Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| state | int | 0=Success, Non‑0=Failure | Yes |
| message | String | Error hint message | Yes |
| data | JSON | Key: device address, Value: base64 image string | Yes |
Response Example
{"id":"abc123456","state":0,"message":"","data":{"172.16.0.53:5555":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDABcQERQRDhcUEhQaGBcbIjklIh8fIkYyNSk5UkhXVVFIUE5bZoNvW2F8Yk5QcptzfIeLkpSSWG2grJ+OqoOPko3/2wBDARgaGiIeIkMlJUONXlBejY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY3/wAARCACgAFgDASIAAh/2Q=="}}Mouse Events
Simulate mouse/touch events on devices. Coordinate range: 0 ~ 1 (float). Leftmost x=0, rightmost x=1; top y=0, bottom y=1.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: mouseevents | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| action | int | 0=Mouse‑down / Touch‑press1=Mouse‑up / Touch‑release2=Mouse move / Touch drag3=Right‑click4=Mouse scroll up5=Mouse scroll down | Yes |
| data | JSON | Coordinate object {"x":0.5,"y":0.5} | Yes |
| └‑ x | float | Horizontal coordinate 0‑1 | Yes |
| └‑ y | float | Vertical coordinate 0‑1 | Yes |
Request Example
{"id":"abc123456","type":"mouseevents","serial":[],"action":0,"data":{"x":0.5,"y":0.5}}Response Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| state | int | 0=Success, Non‑0=Failure | Yes |
| message | String | Error hint message | Yes |
| data | JSON | Always null | Yes |
Response Example
{"id":"abc123456","state":0,"message":"","data":null}Keyboard Events
Simulate hardware key presses. Refer to key‑code table for code values.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: keyboardevents | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| action | int | 0=Key press down1=Key release2=Single key tap | Yes |
| data | JSON | {"code":65} | Yes |
| └‑ code | int | Virtual key‑code number | Yes |
Request Example
{"id":"abc123456","type":"keyboardevents","serial":[],"action":2,"data":{"code":65}}Response Example
{"id":"abc123456","state":0,"message":"","data":null}Run ADB Shell Command
Execute adb‑shell commands on remote devices. Do not add adb shell prefix in cmd field.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: adbcmd | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"cmd":"wm size"} | Yes |
| └‑ cmd | String | adb shell command content without adb shell prefix | Yes |
Request Example
{"id":"abc123456","type":"adbcmd","serial":[],"data":{"cmd":"wm size"}}Response Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| state | int | 0=Success, Non‑0=Failure | Yes |
| message | String | Error hint message | Yes |
| data | JSON | Key: device address; Value: raw command output text | Yes |
Response Example
{"id":"abc123456","state":0,"message":"","data":{"172.16.0.180:5555":"Physical size: 1440x2960\nOverride size: 720x1280\n","172.16.0.53:5555":"Physical size: 1440x2960\nOverride size: 720x1280\n"}}ADB Text Input
Input text via ADB input service.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: adbinput | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"Text":"abc123 test"} | Yes |
| └‑ Text | String | Text string to input | Yes |
Request Example
{"id":"abc123456","type":"adbinput","serial":[],"data":{"Text":"abc123 test"}}Response Example
{"id":"abc123456","state":0,"message":"","data":{"172.16.0.180:5555":"Broadcasting: Intent { act=ADB_INPUT_TEXT flg=0x400000 (has extras) }\nBroadcast completed: result=0\n","172.16.0.53:5555":"Broadcasting: Intent { act=ADB_INPUT_TEXT flg=0x400000 (has extras) }\nBroadcast completed: result=0\n"}}Direct Text Input
Text input via internal control channel.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: textinput | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"Text":"abc123 test"} | Yes |
| └‑ Text | String | Text string to input | Yes |
Request Example
{"id":"abc123456","type":"textinput","serial":[],"data":{"Text":"abc123 test"}}Response Example
{"id":"abc123456","state":0,"message":"","data":""}Get Foreground App Package & Activity
Retrieve currently‑running foreground application package name and activity class name.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: getclass | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
Request Example
{"id":"abc123456","type":"getclass","serial":[]}Response Example
{"id":"abc123456","state":0,"message":"","data":{"172.16.0.180:5555":"com.google.android.apps.nexuslauncher/com.google.android.apps.nexuslauncher.NexusLauncherActivity\n","172.16.0.53:5555":"com.google.android.apps.nexuslauncher/com.google.android.apps.nexuslauncher.NexusLauncherActivity\n"}}Install APK Application
Install local APK file onto remote devices. File path refers to path on your local PC. Target device storage path is configurable inside software Advanced Settings.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: oninstall | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"Path":"E:\\0ZhuoMian\\0‑4\\A\\Apk\\game.apk"} | Yes |
| └‑ Path | String | Full local PC file path of APK, double‑backslash escape required | Yes |
Request Example
{"id":"abc123456","type":"oninstall","serial":[],"data":{"Path":"E:\\0ZhuoMian\\0‑4\\A\\Apk\\game.apk"}}Response Example
{"id":"abc123456","state":0,"message":"","data":""}Upload Local File to Device
Upload arbitrary file from local PC to connected Android devices. Destination folder configurable in Advanced Settings.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: upload | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"Path":"E:\\ZhuoMian\\test.txt"} | Yes |
| └‑ Path | String | Full local PC file path, double‑backslash escape required | Yes |
Request Example
{"id":"abc123456","type":"upload","serial":[],"data":{"Path":"E:\\ZhuoMian\\test.txt"}}Response Example
{"id":"abc123456","state":0,"message":"","data":""}Switch to ADB Input‑Method
Set device input‑method to ADB input service.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: adbime | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
Request Example
{"id":"abc123456","type":"adbime","serial":[]}Response Example
{"id":"abc123456","state":0,"message":"","data":""}APP Operation: Start / Stop / Uninstall / Clear Cache
Perform application lifecycle operations.
Note: For Start, Info field requires
package/classActivity. For Stop / Uninstall / Clear Cache, package name alone is sufficient.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: appaction | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| Action | int | 0=Launch app1=Stop app2=Uninstall app3=Clear application cache | Yes |
| data | JSON | {"Info":"com.android.settings/com.android.settings.Settings"} | Yes |
| └‑ Info | String | Package name or PackageName/ActivityClassName | Yes |
Request ExamplesLaunch App
{"id":"abc123456","type":"appaction","serial":[],"Action":0,"data":{"Info":"com.android.settings/com.android.settings.Settings"}}Stop App
{"id":"abc123456","type":"appaction","serial":[],"Action":1,"data":{"Info":"com.android.settings"}}Uninstall App
{"id":"abc123456","type":"appaction","serial":[],"Action":2,"data":{"Info":"com.android.settings"}}Clear App Cache
{"id":"abc123456","type":"appaction","serial":[],"Action":3,"data":{"Info":"com.android.settings"}}Response Example
{"id":"abc123456","state":0,"message":"","data":{"172.16.0.180:5555":"Starting: Intent { cmp=com.android.settings/.Settings }\n","172.16.0.53:5555":"Starting: Intent { cmp=com.android.settings/.Settings }\nWarning: Activity not started, its current task has been brought to the front\n"}}Set Screen Resolution & DPI
Modify device display width, height and DPI value.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Custom request‑ID; echoed in response | No |
| type | String | Fixed value: dpiinfo | Yes |
| serial | Array | Target device serial list. [] = all devices | Yes |
| data | JSON | {"dpi":320,"w":720,"h":1280} | Yes |
| └‑ dpi | int | Display DPI value | Yes |
| └‑ w | int | Display pixel width | Yes |
| └‑ h | int | Display pixel height | Yes |
Request Example
{"id":"abc123456","type":"dpiinfo","serial":[],"data":{"dpi":320,"w":720,"h":1280}}Response Example
{"id":"abc123456","state":0,"message":"","data":{}}Common Response Field Definition (All Interfaces)
| Field | Meaning |
|---|---|
id | Request‑ID echoed back from your request |
state | 0 success; non‑zero value means error |
message | Human readable error or hint text |
data | Returned payload, varies per API |
This markdown format can be directly pasted to most CMS / website editors supporting markdown rendering.