SmartWeb

1. 概述

SmartWeb 是一款运行于 Android 设备上的本地桥接服务器应用。

其主要功能如下：

- 检查 SmartThings 身份验证状态并协助进行相关的 API 调用。

- 提供通用的 HTTP 代理功能。

- 允许您在实际的 WebView（浏览器）中打开页面以查看最终的 HTML 代码。

- 作为 SmartThings Edge 驱动程序、本地网页和自动化脚本之间的中介。

2. 基本信息

- 默认端口：8088

- 默认地址格式：http://deviceIP:8088

示例：

- http://192.168.219.137:8088

3. 屏幕布局

3.1 服务器选项卡

在“服务器”选项卡中，您可以查看桥接服务器的状态以及如何使用关键 API。

显示内容示例：

- 桥接服务器地址

- /api/forward 使用格式

- /api/web 使用格式

- SmartThings 身份验证状态检查 API

- 后台 WebView 执行 API

3.2 设置选项卡

在“设置”选项卡中，您可以查看使用应用所需的环境设置和状态。

示例：

- 电池优化异常状态

- 通知权限状态

- 查看/复制日志

- 应用版本信息

4. 主要 API

4.1 POST /api/ping

描述：简要检查桥接服务器状态和 SmartThings 身份验证状态。

方法：

- 仅限 POST 请求

示例：

POST http://deviceIP:8088/api/ping

示例响应：

{

"battery": 86,

"bridgeDevice": "phone",

"bridgeVersion": "Version: 2026.05.15",

"serverStartTime": "05/14 03:00",

"stOauthConnected": true,

"accessTokenExpiresAt": 1778773965000,

"accessTokenMinutesLeft": 1332

}

4.2 GET /api/smartthings/devices

描述：

以简洁的格式返回 SmartThings 设备列表。

方法：

- 仅限 GET 请求

示例：

GET http://deviceIP:8088/api/smartthings/devices

示例响应：

{

"items": [

{

"deviceId": "...",

"label": "Google Home Mini Library",

"name": "Google Home"

}

]

}

用途：

- 通过设备名称查找 deviceId

- 搜索扬声器名称

- 根据标签选择设备

4.3 GET /api/forward?url=origin_address

描述：

一个标准的 HTTP 代理。

方法：

- 仅限 GET 请求

示例：

GET http://deviceIP:8088/api/forward?url=https://api.smartthings.com/v1/devices

用途：

- JSON API 调用

- 读取静态 HTML 页面

- SmartThings REST API 调用

特性：

- 可传递大多数请求头

- 如果调用 SmartThings API 时缺少 Authorization 请求头，则自动使用凭据

- 不执行 JavaScript

- 可能难以通过 Cloudflare/浏览器验证页面

注意：

- 不适用于需要执行 JavaScript 的网站

4.4 GET 或 POST /api/web?url=origin_address

描述：在实际的 WebView 中打开页面并返回最终的 HTML。

方法：

- GET 或 POST

用途：

- 需要执行 JavaScript 的网站

- Cloudflare 验证页面

- 未通过 /api/forward 加载的网站

示例：

GET http://deviceIP:8088/api/web?url=https://

或：

POST http://deviceIP:8088/api/web

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

响应：

- 成功时返回最终的 HTML 正文 (text/html)

- 失败时返回错误字符串

特性：

- 像真正的浏览器一样打开页面

- 支持执行 JavaScript

- 速度较慢但稳定可靠

超时参数：

- timeout：秒

- timeoutSeconds：秒

- timeoutMs：毫秒

示例：

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

注意：

- 响应是 HTML 正文本身，而非 JSON。

- 调用者需要解析 HTML 以获取必要的值。

4.5 GET 或 POST /api/webview/run

描述：

在后台 WebView 中运行页面一段时间。

方法：

- GET 或 POST

用途：

- 在后台保持特定页面运行一段时间。

- 保持 JS 操作/页面执行运行。

示例：

GET http://deviceIP:8088/api/webview/run?url=http://hubaddress:port&timeout=60

特性：

- 最多可同时运行 5 个页面。

- 多余的请求会存储在队列中。

4.6 GET /api/webview/stop

描述：

停止后台 WebView 的运行。

方法：

- 目前使用 GET 方法

5. /api/forward 和 /api/web 的区别

/api/forward

- 标准 HTTP 代理

- 速度快

- 适用于 JSON/API 调用

- 不执行 JavaScript

- 适用于静态页面/通用 API

/api/web

- 基于 WebView 的浏览器读取

- 速度慢但稳定

- 可执行 JavaScript

- 支持 Cloudflare/浏览器验证页面

- 适用于需要浏览器打开的页面

推荐标准：

- 通用 API/静态页面：/api/forward

- 需要在浏览器中打开的页面：/api/web

6. 允许的方法总结

仅支持 POST 方法

- /api/ping

- /api/smartthings/token

- /api/smartthings/access-token

仅支持 GET 方法

- /api/smartthings/devices

- /api/forward

GET 或 POST 方法

- /api/web

- /api/webview/run

停止

- /api/webview/stop

7. bridgeDevice 值说明

/api/ping 的 bridgeDevice 为以下之一：

- tv

- pad

- phone

判定标准：

- tv：Android TV / Leanback 设备

- pad：最小屏幕宽度 >= 600

- phone：其他

8. 使用示例

8.1 检查服务器状态

POST /api/ping

8.2 检查设备列表

GET /api/smartthings/devices

8.3 通用 API 代理

GET /api/forward?url=https://api.smartthings.com/v1/devices

8.4 访问网站（需要浏览器）

GET /api/web?url=https://

9. 总结

SmartWeb 是运行在 Android 设备上的本地桥接服务器。要点：

- 检查 SmartThings 身份验证状态

- 简易设备列表 API

- 标准 HTTP 代理 (/api/forward)

- 基于 WebView 的浏览器读取 (/api/web)

- 在后台运行 WebView (/api/webview/run)

特别是，/api/web 功能允许您使用实际的浏览器方法读取那些难以通过标准 HTTP 请求读取的页面。