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 요청으로는 읽기 어려운 페이지도
실제 브라우저 방식으로 읽어올 수 있습니다.