前端接口

RobotBrowser SDK 在浏览器中运行，负责弹出执行窗口、连接 WebSocket 实时画面、驱动任务执行。

SDK 集成

页面中引入一个脚本即可：

<script src="//webtask.phpers.cn/static/sdk/robot-browser.js"></script>

加载后全局暴露 RobotBrowser 对象。前端只需调用 run()，签名参数由服务端生成（见后端签名机制）。

run(params, callback)

核心入口。创建执行弹窗、连接 WebSocket、启动任务，实时展示浏览器画面和步骤进度。

// 服务端按 signature 规则生成 params（含 task_id, app_id, timestamp, sign, tuid, client_id）
var params = {
    task_id:   12345,
    app_id:    'your_app_id',
    timestamp: Math.round(Date.now() / 1000),
    sign:      '...',
    tuid:      'order_123456',
    client_id: '936ebb63059d49edc4bf52ce636f0a00',
};

RobotBrowser.run(params, function(err, data) {
    if (err) return console.error('失败:', err.message);
    console.log('完成:', data.status, data.result);
});

stop(params, callback)

通过 task_id + tuid 停止正在运行的任务（tuid 可能重复，必须携带 task_id 定位）。

closeDialog()

手动关闭当前执行弹窗。任务失败或停止时弹窗不会自动关闭。

RobotBrowser.run(params, function(err) {
    if (err) RobotBrowser.closeDialog();
});

回调数据格式

后端接口

后端 REST API 供第三方服务端调用。所有接口通过 MD5 签名 鉴权，对外接口如下。

接口总览

说明：create/execute/formSubmit/serverStep 为浏览器 SDK 及调度器内部使用的接口，第三方服务端一般无需直接调用。

Base URL：https://webtask.phpers.cn/api.php，返回值格式 { code:0, data:{...} }。

签名机制

公共参数

签名算法

所有接口统一签名格式：md5(app_id + timestamp + app_secret)。

代码示例

<?php
$sign = md5($appId . time() . $appSecret);

sign := fmt.Sprintf("%x", md5.Sum([]byte(appId + now + appSecret)))

sign = hashlib.md5((app_id + now + app_secret).encode()).hexdigest()

start · POST /api.php/task.process/start

直接启动运行。一步完成创建进程+执行，适用于服务端后台主动触发任务的场景。

返回：{ tuid, status_app_id, status_timestamp, status_sign }

sync_start · POST /api.php/task.process/sync_start

同步启动运行。阻塞等待任务执行完成后再返回结果，适用于需要直接拿结果的服务端场景（无需轮询 status）。

注意：任务执行期间请求会一直挂起（占用 PHP worker），任务执行时间较长时请适当调大 timeout。

可用步骤类型（来自 step_types）

自定义 steps 时，每个节点的 type 须填下表中的类型标识，params 按对应参数填写。下表由 step_types 表动态生成（仅列出启用中的步骤），库里新增 / 修改步骤类型后刷新本页即可同步。

示例——用 steps 直接指定"执行 JS 取页面标题长度"，替代任务默认流程：

{
  "steps": [
    {
      "type": "js",
      "return_var": "js",
      "params": { "code": "return document.title.length" }
    }
  ]
}

数组与 JSON 字符串两种传法等价。例如同样可传 steps='[{"type":"js","return_var":"js","params":{"code":"return document.title.length"}}]'；多个步骤按数组顺序依次执行，返回结构见下文。

返回结构说明：

{
  "code": 0,
  "msg": "success",
  "data": {
    "tuid": "test",            // 业务幂等键（原样返回）
    "status": "completed",      // 终态：completed 成功 / failed 失败 / stopped 被停止
    "result": {                 // 任务返回值（各步骤返回变量汇总）
      "js": 2,                  // 例：任务里某步骤返回变量 js = 2
      "cookie": "abc123"        // 例：另一返回变量
    },
    "error_msg": ""             // status=failed 时才有值，为失败原因
  }
}

JS 读取示例——以任务返回变量 js = 2 为例：

const data = resp.data;                      // 或 resp.json().data
if (data.status === 'completed') {
    const js = data.result.js;                // 直接读取变量 js，得到 2
    console.log('js =', js);                  // 输出: js = 2
} else {
    console.log('失败:', data.error_msg);
}

若任务使用"返回值变量"（如 return_var=funca），返回结构为 { "funca": { "returns": { ... } } }，读取方式：data.result.funca.returns.变量名。

action · POST /api.php/task.process/action

向处于 保持激活（keep_live）状态的进程发送命令，触发对应分支执行，同步等待分支执行完并返回分支的返回值。适用于"进程常驻页面、外部按需下发 JS 操作或读取数据"的场景。

前提：进程必须运行到 keep_live 步骤且保持激活状态（status 接口可见 current_step.type = "keep_live"）。

返回：{ code:0, data:{ 分支返回值 } }——分支执行后新增/修改的返回变量。例如分支内步骤设了 return_var=text 且返回"你好"，则返回 { code:0, data:{ text:"你好" } }。

退出：调用 action=exit 可退出 keep_live 继续执行后续步骤；也可用 stop 接口停止进程。

status · GET /api.php/task.process/status

查询进程的当前状态和结果。

注意：status / stop / action 接口仅校验签名正确性、不校验时间戳过期（长时间运行的任务签名由服务端生成，无法刷新），与公共参数表中"3600 秒过期"规则不同。

返回：{ tuid, status, current_step, result, error_msg }

stop · GET /api.php/task.process/stop

停止正在运行或等待中的进程。