SmartWeb

حول SmartWeb

١. نظرة عامة

SmartWeb هو تطبيق خادم وسيط محلي يعمل على أجهزة أندرويد.

تتلخص وظائفه الرئيسية فيما يلي:

- التحقق من حالة مصادقة SmartThings والمساعدة في استدعاءات واجهة برمجة التطبيقات (API) ذات الصلة.

- توفير وظائف وكيل HTTP عامة.

- السماح بفتح صفحة في متصفح ويب (WebView) لقراءة كود HTML النهائي.

- العمل كوسيط بين برامج تشغيل SmartThings Edge وصفحات الويب المحلية وبرامج التشغيل الآلي.

٢. معلومات أساسية

- المنفذ الافتراضي: 8088

- تنسيق العنوان الافتراضي: http://deviceIP:8088

مثال:

- http://192.168.219.137:8088

٣. تخطيط الشاشة

٣.١ علامة تبويب الخادم

في علامة تبويب الخادم، يمكنك التحقق من حالة خادم الوسيط وكيفية استخدام واجهات برمجة التطبيقات الرئيسية.

أمثلة على المحتوى المعروض:

- عنوان خادم الجسر

- تنسيق استخدام /api/forward

- تنسيق استخدام /api/web

- واجهة برمجة تطبيقات التحقق من حالة مصادقة SmartThings

- واجهة برمجة تطبيقات تنفيذ WebView في الخلفية

3.2 علامة تبويب الإعدادات

في علامة تبويب الإعدادات، يمكنك التحقق من إعدادات البيئة والحالة المطلوبة لاستخدام التطبيق.

أمثلة:

- حالة استثناء تحسين البطارية

- حالة إذن الإشعارات

- عرض/نسخ السجلات

- معلومات إصدار التطبيق

4. واجهات برمجة التطبيقات الرئيسية

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"

}

] }

الاستخدامات:

- البحث عن معرّف الجهاز باستخدام اسمه

- البحث عن أسماء مكبرات الصوت

- اختيار الأجهزة بناءً على التصنيفات

4.3 GET /api/forward?url=origin_address

الوصف:

خادم وكيل HTTP قياسي.

الطريقة:

- طلب GET فقط

مثال:

GET http://deviceIP:8088/api/forward?url=https://api.smartthings.com/v1/devices

الاستخدامات:

- استدعاءات واجهة برمجة تطبيقات JSON

- قراءة صفحات HTML الثابتة

- استدعاءات واجهة برمجة تطبيقات SmartThings REST

الميزات:

- تمرير معظم رؤوس الطلبات

- استخدام بيانات الاعتماد تلقائيًا في حال عدم وجود رأس Authorization عند استدعاء واجهات برمجة تطبيقات SmartThings

- لا يتم تنفيذ جافا سكريبت

- قد يكون غير آمن ضد صفحات التحقق من صحة Cloudflare/المتصفح

تنبيه:

- غير مناسب للمواقع التي تتطلب تنفيذ جافا سكريبت

4.4 طلب 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

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

الاستجابة:

- نص HTML النهائي (text/html) في حالة النجاح

- نص الخطأ في حالة الفشل

الميزات:

- يفتح الصفحة كما لو كان متصفحًا حقيقيًا

- إمكانية تنفيذ جافا سكريبت

- بطيء ولكنه موثوق

معاملات المهلة الزمنية:

- timeout: ثوانٍ

- timeoutSeconds: ثوانٍ

- timeoutMs: بالمللي ثانية

مثال:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

ملاحظة:

- الاستجابة هي نص HTML نفسه، وليس JSON.

- يحتاج المُستدعي إلى تحليل HTML للحصول على القيم المطلوبة.

4.5 GET أو POST /api/webview/run

الوصف:

تشغيل صفحة في WebView في الخلفية لفترة زمنية محددة.

الطريقة:

- GET أو POST

الاستخدامات:

- إبقاء صفحة معينة قيد التشغيل في الخلفية لفترة زمنية محددة.

- إبقاء عمليات جافا سكريبت/تنفيذ الصفحة قيد التشغيل.

مثال:

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

- لا يُنفذ جافا سكريبت

- مناسب للصفحات الثابتة/واجهات برمجة التطبيقات العامة

/api/web - قراءة من المتصفح باستخدام WebView - بطيء ولكنه موثوق - جافا سكريبت قابل للتنفيذ

- يدعم صفحات التحقق من صحة Cloudflare/المتصفح

- مناسب للصفحات التي تتطلب متصفحًا

المعايير المُوصى بها:

- واجهات برمجة التطبيقات العامة/الصفحات الثابتة: /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

- pad: أصغر عرض شاشة Dp ≥ 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 - واجهة برمجة تطبيقات بسيطة لعرض قائمة الأجهزة - وكيل HTTP قياسي (/api/forward) - قراءة المتصفح باستخدام WebView (/api/web) - تشغيل WebView في الخلفية (/api/webview/run)

على وجه الخصوص، تتيح لك وظيفة /api/web قراءة الصفحات التي يصعب قراءتها عبر طلبات HTTP القياسية باستخدام متصفح فعلي.

• ↗يلعب دورًا في التحقق من حالة مصادقة SmartThings والمساعدة في استدعاءات واجهة برمجة التطبيقات ذات الصلة.