ziniao-webdriver-doc (Ziniao WebDriver Documentation)

When to Use / Not to Use

Scenario	Action
Need to understand what Ziniao WebDriver is and what it can do	Read this Skill
Need to make design decisions for automation integration/framework selection	Read this Skill
Need to check the request/response format of a specific interface	Follow the access path in §Deep Dive on Demand of this Skill, then read the corresponding reference/ file
Need to view sample code for various languages/frameworks	Do not read this Skill → Directly read `reference/framework-examples.md`

Level 0: Positioning and Boundaries

What It Is

Ziniao Browser WebDriver is a local automation control interface provided by Ziniao Browser. After launching Ziniao Browser in WebDriver mode via command-line parameters, the browser starts an HTTP service locally. Developers can manage store windows through JSON APIs, and use frameworks like Selenium / Puppeteer / Playwright / DrissionPage to connect to the debugging port, achieving automated control of the store browser.

Capability Overview

Capability Domain	Description
Client Launch Control	Launch/exit Ziniao Browser into WebDriver mode via command-line parameters
Authentication and Login	Complete device authorization, account login, and obtain store list via API
Store Window Management	Launch/close specified store windows, obtain debugging port (debuggingPort)
Automation Framework Integration	Return debugging port for connection with Selenium/Puppeteer/Playwright/DrissionPage
Kernel Management	Detect/download/update browser kernel
Cache and Session	Clear local/online cache, manage Cookie policies
Plugin Management	Load specified plugins when launching stores, query plugin installation status

What It Doesn't Do (Boundaries)

It is not a general-purpose browser automation solution—only applicable to Ziniao Browser client
It does not provide the WebDriver driver itself—you need to download the matching version of ChromeDriver according to the returned
```
core_version
```
It does not handle e-commerce platform business logic—only provides browser window control capabilities
It does not provide cloud deployment—only supports local operation (remote control can be enabled via
```
--listen_ip
```
)

Level 1: Architecture and Process

Core Concepts

WebDriver Mode: Launch Ziniao Browser with the

--run_type=web_driver

parameter to enter automation control mode. In this mode, the browser starts an HTTP service on a specified local port and accepts JSON-formatted API calls. The Ziniao main process must be closed before launching.

HTTP IPC Communication: All APIs are POST requests in JSON format with UTF-8 encoding. The communication port is specified via the

--port

parameter, and the address is

http://127.0.0.1:{port}

. Each request must carry an

action

field to identify the operation type and a

requestId

as a globally unique identifier. It is recommended to set the timeout to over 120 seconds.

Store Window (browserOauth / browserId): Ziniao uses "store" as the smallest management unit. Call

getBrowserList

to obtain the store list and encrypted ID (

browserOauth

), then launch the specified store window via

startBrowser

, which returns

debuggingPort

for automation framework connection. If opening a store directly using the return value of

getBrowserList

, only pass

browserOauth

; assign

browserId

only when you need to open it with a plaintext store ID.

Kernel Version Matching:

startBrowser

returns

core_type

(e.g., Chromium) and

core_version

(e.g., 119.1.0.16). Developers must use a ChromeDriver with the corresponding major version number (e.g., 119.x) for connection, otherwise automation will fail.

Overall Process

mermaid

graph LR
  A[Apply for Permissions] --> B["Launch Client<br>(Clean residual processes first)"]
  B --> C["updateCore<br>Check Kernel<br>⚠ Credentials Required"]
  C --> D["getBrowserList<br>Obtain Store List<br>⚠ Credentials Required"]
  D --> E["startBrowser<br>Launch Store Window<br>⚠ Credentials Required"]
  E --> F["Download Matching<br>ChromeDriver"]
  F --> G["Connect to Automation Framework<br>Selenium, etc."]
  G --> H[Execute Automation Operations]
  H --> I["stopBrowser<br>Close Store<br>⚠ Credentials Required"]
  I --> J[exit<br>Exit Client]

Apply for Permissions: Enable WebDriver permissions on the Ziniao Open Platform
Launch Client: Clean residual processes first (see §Key Pitfalls), then launch Ziniao Browser via command line with required parameters:
```
--run_type=web_driver --ipc_type=http --port={port}
```
updateCore: Must carry company/username/password, poll to check if the kernel is ready (statusCode==0), automatically download if missing
getBrowserList: Pass company/username/password to obtain the store list
startBrowser: Pass company/username/password + browserOauth, return debuggingPort and core_version
Download ChromeDriver: Download the matching ChromeDriver according to the major version number of
```
core_version
```
(not the system Chrome version)
Connect to Framework: Use
```
127.0.0.1:{debuggingPort}
```
+ matching version of ChromeDriver to connect to Selenium, etc.
Shutdown: Use
```
stopBrowser
```
(credentials required) to close the store window, use
```
exit
```
to exit the client

Capability Summary Table

API Action	Responsibility	Key Input	Key Output	Credentials Required
updateCore	Detect/download kernel	company, username, password	statusCode, msg(progress)	Yes
applyAuth	Device authorization	company, username, password	statusCode	Yes
getBrowserList	Obtain store list	company, username, password	browserList[{browserOauth, browserName, siteId...}]	Yes
startBrowser	Launch store window	company, username, password, browserOauth/browserId	debuggingPort, core_version, core_type	Yes
stopBrowser	Close store window	company, username, password, browserOauth/browserId	statusCode	Yes
logout	Log out	None	statusCode	No
exit	Exit client process	None	statusCode	No
ClearCache	Clear local cache	browserOauths[]	statusCode	No
ClearOnline	Clear online cache	company, username, password, browserOauth, type(1/2/3)	statusCode	Yes
getPluginInstalled	Query plugin installation status	browserId, pluginIds	install_status	No
getRunningInfo	Obtain running stores	None	browsers[]	No

Key Pitfalls

The following are high-frequency pitfalls in actual practice, please strictly abide by them when writing automation scripts.

Pitfall 1: Credential Consistency

All interfaces marked "Credentials Required" (

updateCore

getBrowserList

startBrowser

stopBrowser

ClearOnline

) must carry the complete company/username/password every time they are called, not just "login-type" interfaces.

updateCore

is particularly easy to miss—although it seems to only detect the kernel, the Ziniao server requires credential verification to return the kernel status.

Pitfall 2: Error Message Handling

When the API returns an error, prioritize reading the content of the
err
field to locate the problem, rather than relying solely on the

statusCode

number. The

err

field contains specific Chinese error descriptions, which are the most valuable troubleshooting information.

Encoding Note: The Chinese in

err

may appear garbled if the response body is not decoded in UTF-8 correctly, making it impossible to locate the root cause. Ensure that the HTTP client decodes the response body in UTF-8 (for Python

requests

library, set

response.encoding = 'utf-8'

, or use

response.content.decode('utf-8')

Pitfall 3: Residual Process Cleanup

After Ziniao fails to launch or exits abnormally, multiple child processes (main process + kernel process) may remain. Restarting without cleaning them up will cause port occupation and repeated failures. Before each launch and before retrying after a failure, ensure all Ziniao-related processes have been terminated.

Cleanup Commands:

bash

# Windows (PowerShell)
Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force

# macOS / Linux
pkill -f ziniao || true

Pitfall 4: ChromeDriver Version Must Match Ziniao Kernel

The kernel version of Ziniao Browser (

core_version

) has nothing to do with the Chrome browser version installed on the system. You must extract the major version number from

core_version

returned by

startBrowser

(e.g.,

119.1.0.16

→

) and download the corresponding ChromeDriver version.

Recommended Strategy:

After obtaining
```
core_version
```
for the first time, check if the ChromeDriver of this major version already exists in the local cache directory
If not, download the corresponding version from https://googlechromelabs.github.io/chrome-for-testing/
Cache it to a local directory (e.g.,
```
./chromedriver_cache/{major_version}/chromedriver
```
) for reuse in subsequent operations

Environment Requirements

Item	Requirement
Windows	Ziniao V5 (5.X.X.X) or V6 (6.16.0.126+)
macOS	Ziniao V6 (6.15.0.44+)
Linux	Ziniao V6 (6.25.3.3+)
Communication Protocol	HTTP POST, JSON, UTF-8
Timeout Setting	≥ 120 seconds
Prerequisite for Launch	Ziniao main process must be completely closed
Recommended Framework	Selenium (Playwright/Puppeteer will be detected as automation)

Deep Dive on Demand (Level 2 Routing Table)

Rule: Do not actively load the following content. Only read the corresponding reference/ file according to the routing table when you clearly need to understand a certain detail.

What You Need to Understand	File to Read
Core workflow interfaces (applyAuth/getBrowserList/startBrowser)	`reference/api-core.md`
Auxiliary management interfaces (stopBrowser/logout/exit/cache/plugin/updateCore)	`reference/api-auxiliary.md`
Detailed description of command-line parameters for launching the client	`reference/startup-params.md`
Sample code and download links for various languages/frameworks	`reference/framework-examples.md`
Permission activation, account configuration, and common troubleshooting	`reference/prerequisites.md`

ziniao-webdriver-doc

NPX Install

Tags

SKILL.md Content (Chinese)