SmartThings Web Host

۱. مرور کلی

SmartWeb یک برنامه سرور پل محلی است که بر روی دستگاه‌های اندروید اجرا می‌شود.

اهداف اصلی آن به شرح زیر است:

- وضعیت احراز هویت SmartThings را بررسی می‌کند و به فراخوانی‌های API مرتبط کمک می‌کند.

- عملکرد عمومی پروکسی HTTP را فراهم می‌کند.

- به شما امکان می‌دهد صفحه‌ای را در یک WebView (مرورگر) واقعی باز کنید تا HTML نهایی را بخوانید.

- به عنوان واسطه‌ای برای درایورهای SmartThings Edge، صفحات وب محلی و اسکریپت‌های اتوماسیون عمل می‌کند.

۲. اطلاعات اولیه

- پورت پیش‌فرض: ۸۰۸۸

- قالب آدرس پیش‌فرض: http://deviceIP:۸۰۸۸

مثال:

- http://192.168.219.137:8088

۳. طرح‌بندی صفحه

۳.۱ تب سرور

در تب سرور، می‌توانید وضعیت سرور پل و نحوه استفاده از APIهای کلیدی را بررسی کنید.

نمونه‌هایی از محتوای نمایش داده شده:

- آدرس سرور پل

- قالب استفاده /api/forward

- قالب استفاده /api/web

- API بررسی وضعیت احراز هویت SmartThings

- API اجرای WebView در پس‌زمینه

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 را در قالبی ساده برمی‌گرداند.

روش:

- فقط دریافت

مثال:

دریافت http://deviceIP:8088/api/smartthings/devices

پاسخ نمونه:

{

"items": [

{

"deviceId": "...",

"label": "کتابخانه کوچک گوگل هوم",

"name": "گوگل هوم"

}

]

}

کاربردها:

- هنگام یافتن شناسه دستگاه با نام دستگاه

- جستجوی نام بلندگوها

- انتخاب دستگاه‌ها بر اساس برچسب‌ها

۴.۳ 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

ویژگی‌ها:

- اکثر هدرهای درخواست را ارسال می‌کند

- در صورت عدم وجود هدر مجوز هنگام فراخوانی APIهای SmartThings، به طور خودکار از اعتبارنامه‌ها استفاده می‌کند

- جاوا اسکریپت را اجرا نمی‌کند

- ممکن است در برابر صفحات اعتبارسنجی Cloudflare/مرورگر ضعیف باشد

احتیاط:

- برای سایت‌هایی که نیاز به اجرای جاوا اسکریپت دارند مناسب نیست

۴.۴ GET یا POST /api/web?url=origin_address

توضیحات: صفحه را در یک WebView واقعی باز می‌کند و HTML نهایی را برمی‌گرداند.

روش:

- GET یا POST

کاربرد:

- سایت‌هایی که نیاز به اجرای جاوا اسکریپت دارند

- صفحات اعتبارسنجی Cloudflare

- سایت‌هایی که از طریق /api/forward بارگذاری نمی‌شوند

مثال:

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

یا:

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

نوع محتوا: application/json

{

"url": "https://",

"timeoutMs": 20000

}

پاسخ:

- بدنه نهایی HTML (text/html) در صورت موفقیت

- رشته خطا در صورت شکست

ویژگی‌ها:

- صفحه را مانند یک مرورگر واقعی باز می‌کند

- اجرای جاوا اسکریپت امکان‌پذیر است

- کند اما قوی

پارامترهای Timeout:

- timeout: seconds

- timeoutSeconds: seconds

- timeoutMs: میلی‌ثانیه

مثال:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

توجه:

- پاسخ، خودِ بدنه HTML است، نه JSON.

- فراخواننده برای دریافت مقادیر لازم، باید HTML را تجزیه کند.

۴.۵ GET یا POST /api/webview/run

توضیحات:

یک صفحه را در یک WebView پس‌زمینه برای مدت زمان مشخصی اجرا می‌کند.

روش:

- GET یا POST

موارد استفاده:

- یک صفحه خاص را برای مدت زمان مشخصی در پس‌زمینه اجرا نگه می‌دارد.

- عملیات JS/اجرای صفحه را در حال اجرا نگه می‌دارد.

مثال:

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

ویژگی‌ها:

- حداکثر ۵ صفحه را به طور همزمان اجرا می‌کند. - درخواست‌های اضافی در صف ذخیره می‌شوند.

۴.۶ GET /api/webview/stop

توضیحات:

اجرای یک WebView در پس‌زمینه را متوقف می‌کند.

روش:

- در حال حاضر به عنوان GET استفاده می‌شود

5. تفاوت بین /api/forward و /api/web

/api/forward

- پروکسی HTTP استاندارد

- سریع

- مناسب برای فراخوانی‌های JSON/API

- جاوا اسکریپت را اجرا نمی‌کند

- مناسب برای صفحات استاتیک/API های عمومی

/api/web

- خواندن مرورگر مبتنی بر WebView

- کند اما قوی

- قابل اجرا با جاوا اسکریپت

- پشتیبانی از صفحات اعتبارسنجی 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

bridgeDevice برای /api/ping یکی از موارد زیر است:

- tv

- pad

- phone

معیارهای تعیین:

- tv: Android TV / Leanback devices

- pad: smallerScreenWidthDp >= 600

- phone: Other

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 دشوار است، با استفاده از یک روش مرورگر واقعی بخوانید.