SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsziniao-webdriver-doc

ziniao-webdriver-doc

Agents & models

View repository

Updated 10-16 01:56

About this skill

ziniao-webdriver-doc (Ziniao WebDriver documentation)

When to use / not use

Scenario Approach
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 look up the request/response format of a certain interface Read this Skill's §Go Deeper on Demand to get the path, then read the corresponding reference/ file
Need to view example code for various languages/frameworks Do not read this Skill → read directly reference/framework-examples.md

Level 0: Positioning and boundaries

What it is

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

Capability overview

Capability domain Description
Client startup control Start/exit Ziniao Browser via command-line parameters to enter WebDriver mode
Authentication and login Complete device authorization, account login, and obtain the store list through the API
Store window management Start/close specified store windows and obtain the debugging port (debuggingPort)
Automation framework integration Return the debugging port for Selenium/Puppeteer/Playwright/DrissionPage to connect to
Kernel management Detect/download/update the browser kernel
Cache and sessions Clear local/online cache and manage Cookie policies
Plugin management Load specified plugins when starting a store and query plugin installation status

What it does not do (boundaries)

  • It is not a general browser automation solution—it applies only to the Ziniao Browser client
  • It does not provide the WebDriver driver itself—you need to download a matching version of ChromeDriver yourself based on the returned core_version Download the matching version of ChromeDriver yourself
  • It does not handle e-commerce platform business logic—it only provides browser window control capabilities
  • It does not provide cloud deployment—it supports only local operation (through --listen_ip it can open remote control)

Level 1: Architecture and process

Core concepts

WebDriver mode: Start Ziniao Browser with the --run_type=web_driver parameter to make it enter automation control mode. In this mode, the browser starts an HTTP service on a specified local port and accepts JSON-format API calls. The Ziniao main process must be closed before startup.

HTTP IPC communication: All APIs are POST requests, JSON format, UTF-8 encoding. Specify the communication port through the --port parameter; the address is http://127.0.0.1:{port}. Each request must carry the action field to identify the operation type,requestId as a globally unique identifier. A timeout of 120 seconds or more is recommended.

Store window (browserOauth / browserId): ZiNiao uses "store" as the smallest management unit. Call getBrowserList to get the store list and encrypted ID (browserOauth), then via startBrowser start the specified store window, returning debuggingPort for the automation framework to connect. If you directly use the getBrowserList return value to open the store, you only need to pass browserOauth; only assign browserId。

Kernel version matching：startBrowser returns core_type(e.g. Chromium) and core_version(e.g. 119.1.0.16); developers must connect using the ChromeDriver with the corresponding major version number (e.g. 119.x), otherwise automation will fail.

Process overview

graph LR
  A[申请权限] --> B["启动客户端<br>(先清理残留进程)"]
  B --> C["updateCore<br>检测内核<br>⚠ 需凭据"]
  C --> D["getBrowserList<br>获取店铺列表<br>⚠ 需凭据"]
  D --> E["startBrowser<br>启动店铺窗口<br>⚠ 需凭据"]
  E --> F["下载匹配的<br>ChromeDriver"]
  F --> G["连接自动化框架<br>Selenium等"]
  G --> H[执行自动化操作]
  H --> I["stopBrowser<br>关闭店铺<br>⚠ 需凭据"]
  I --> J[exit<br>退出客户端]
  1. Apply for permissions: enable WebDriver permissions on the ZiNiao open platform
  2. Start the client: first clean up residual processes (see §Key pitfalls), then start the ZiNiao browser from the command line; required parameters:--run_type=web_driver --ipc_type=http --port={端口}
  3. updateCore：must carry company/username/password, poll to check whether the kernel is ready (statusCode==0), and automatically download it if missing
  4. getBrowserList: pass in company/username/password to get the store list
  5. startBrowser: pass in company/username/password + browserOauth, returning debuggingPort and core_version
  6. Download ChromeDriver: according to core_version major version number, download the matching ChromeDriver (not the system Chrome version）
  7. Connect the framework: use 127.0.0.1:{debuggingPort} + the matching version of ChromeDriver to connect Selenium, etc.
  8. Close：stopBrowser(credentials required) close the store window,exit exit the client

Capability summary table

Interface 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 Get store list company, username, password browserList[{browserOauth, browserName, siteId...}] Yes
startBrowser Start 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 Get opened stores None browsers[] No

Key pitfalls

The following are all high-frequency pitfalls in real-world practice; be sure to strictly follow them when writing automation scripts.

Pitfall 1: Credential consistency

All interfaces marked "credentials required" (updateCore、getBrowserList、startBrowser、stopBrowser、ClearOnline）every call must carry the complete company/username/password, not just "login-type" interfaces.updateCore This is especially easy to overlook—it seems like just a kernel detection, but the Purple Bird server requires credential-based identity verification before returning the kernel status.

Trap 2: Error Message Handling

When the API returns an error,prioritize reading the contents of the err field to pinpoint the problem, rather than relying only on the statusCode number.err The field contains a specific Chinese error description and is the most valuable troubleshooting information.

Encoding note:err The Chinese in may appear garbled if the response body is not correctly decoded as UTF-8, making it impossible to locate the root cause.Be sure to ensure the HTTP client decodes the response body as UTF-8（Python requests The library needs to be configured with response.encoding = 'utf-8', or use response.content.decode('utf-8')）。

Trap 3: Residual Process Cleanup

After Purple Bird fails to start or exits abnormally, multiple child processes may remain (main process + kernel process). If you restart without cleaning them up, it will cause port occupation and repeated failures.Before each startup and before retrying after a failure, you must ensure that all Purple Bird-related processes have been terminated.

Cleanup command:

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

# macOS / Linux
pkill -f ziniao || true

Trap 4: ChromeDriver Version Must Match the Purple Bird Kernel

The kernel version of the Purple Bird browser (core_version）is unrelated to the version of the Chrome browser installed on the system. You must extract the major version number from the startBrowser returned by core_version (e.g., 119.1.0.16 → 119), and download the corresponding version of ChromeDriver.

Recommended strategy:

  1. After obtaining core_version for the first time, check whether the local cache directory already has the ChromeDriver for that major version
  2. If not, download the corresponding version from https://googlechromelabs.github.io/chrome-for-testing/ Download the corresponding version
  3. cache it to a local directory (e.g., ./chromedriver_cache/{major_version}/chromedriver), and reuse it afterward

Environment Conventions

Item Requirement
Windows Purple Bird V5 (5.X.X.X) or V6 (6.16.0.126+)
macOS Purple Bird V6 (6.15.0.44+)
Linux Purple Bird V6 (6.25.3.3+)
Communication protocol HTTP POST, JSON, UTF-8
Timeout setting ≥ 120 seconds
Startup prerequisite The Purple Bird main process must be completely closed
Recommended framework Selenium (Playwright/Puppeteer will be detected as automation)

Go deeper as needed (Level 2 routing table)

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

You need to understand Read file
Core workflow APIs (applyAuth/getBrowserList/startBrowser) reference/api-core.md
Auxiliary management APIs (stopBrowser/logout/exit/cache/plugin/updateCore) reference/api-auxiliary.md
Detailed description of the command-line parameters for starting 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