SmartWeb

SmartWeb 정보

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

• ↗SmartThings 인증 상태를 확인하고 관련 API 호출을 도와주는 역할을 합니다.