SmartThings Web Host

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 請求讀取的頁面。