SmartThings Web Host

1. 개요

SmartWeb은 안드로이드 기기에서 동작하는 로컬 브리지 서버 앱입니다.

주요 목적은 다음과 같습니다.

- SmartThings 인증 상태를 확인하고 관련 API 호출을 돕습니다.

- 일반 HTTP 프록시 기능을 제공합니다.

- 실제 WebView(브라우저)로 페이지를 열어 최종 HTML을 읽어올 수 있습니다.

- SmartThings Edge 드라이버, 로컬 웹페이지, 자동화 스크립트의 중계 역할을 합니다.

2. 기본 정보

- 기본 포트: 8088

- 기본 주소 형식: http://기기IP: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://기기IP:8088/api/ping

응답 예:

{

"battery": 86,

"bridgeDevice": "phone",

"bridgeVersion": "버전: 2026.05.15",

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

"stOauthConnected": true,

"accessTokenExpiresAt": 1778773965000,

"accessTokenMinutesLeft": 1332

}

4.2 GET /api/smartthings/devices

설명:

SmartThings 기기 목록을 간단한 형태로 반환합니다.

메서드:

- GET만 허용

예:

GET http://기기IP:8088/api/smartthings/devices

응답 예:

{

"items": [

{

"deviceId": "...",

"label": "구글홈미니 서재",

"name": "Google Home"

}

]

}

용도:

- 기기 이름으로 deviceId를 찾을 때

- 스피커 이름 검색

- 라벨 기반 기기 선택

4.3 GET /api/forward?url=원본주소

설명:

일반 HTTP 프록시입니다.

메서드:

- GET만 허용

예:

GET http://기기IP: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=원본주소

설명:

실제 WebView로 페이지를 열고 최종 HTML을 반환합니다.

메서드:

- GET 또는 POST

용도:

- JavaScript 실행이 필요한 사이트

- Cloudflare 검증 페이지

- /api/forward로 읽히지 않는 사이트

예:

GET http://기기IP:8088/api/web?url=https://

또는:

POST http://기기IP:8088/api/web

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

응답:

- 성공 시 최종 HTML 본문(text/html)

- 실패 시 에러 문자열

특징:

- 실제 브라우저처럼 페이지를 엶

- JavaScript 실행 가능

- 느리지만 강함

타임아웃 파라미터:

- timeout: 초

- timeoutSeconds: 초

- timeoutMs: 밀리초

예:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

주의:

- 응답은 JSON이 아니라 HTML 본문 자체

- 필요한 값은 호출한 쪽에서 HTML 파싱 필요

4.5 GET 또는 POST /api/webview/run

설명:

백그라운드 WebView에서 페이지를 일정 시간 실행합니다.

메서드:

- GET 또는 POST

용도:

- 특정 페이지를 일정 시간 백그라운드에서 유지

- JS 동작/페이지 실행 유지

예:

GET http://기기IP:8088/api/webview/run?url=http://허브주소:포트&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: smallestScreenWidthDp >= 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은 안드로이드 기기 위에서 동작하는 로컬 브리지 서버입니다.

핵심 포인트:

- SmartThings 인증 상태 확인

- 간단한 기기 목록 API

- 일반 HTTP 프록시 (/api/forward)

- WebView 기반 브라우저 읽기 (/api/web)

- 백그라운드 WebView 실행 (/api/webview/run)

특히 /api/web 기능을 통해 일반 HTTP 요청으로는 읽기 어려운 페이지도

실제 브라우저 방식으로 읽어올 수 있습니다.