انتقل إلى المحتوى الرئيسي

المقدمة

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل WS (WebSocket) استقبال الإشعارات في الوقت الحقيقي - تحديثات المحتوى، تغييرات الطلبات، إجراءات المستخدم - من خلال إنشاء اتصالات دائمة للحصول على تحديثات فورية دون الحاجة للاستعلام المتكرر، مما يمكّن الميزات الحية مثل الإشعارات، الدردشة الحية، ولوحات المعلومات في الوقت الحقيقي.

فكر في الأمر كنظام إشعارات في الوقت الحقيقي - بدلاً من السؤال المتكرر "هل هناك شيء جديد؟" (الاستعلام المتكرر)، يبقي WebSocket الاتصال مفتوحًا ويدفع الخادم التحديثات إليك على الفور عند حدوث الأحداث.

📖 شرح بسيط​

تحتاج كل تطبيق حديث إلى تحديثات في الوقت الحقيقي:

  • 🔔 إشعارات حية - تنبيهات فورية عند حدوث شيء ما
  • 💬 دردشة حية - مراسلة في الوقت الحقيقي بين المستخدمين
  • 📊 لوحات معلومات حية - إحصائيات وقياسات تتحدث تلقائيًا
  • 🛒 تحديثات الطلبات - تغييرات فورية في حالة الطلب
  • 📝 تحديثات المحتوى - تغييرات ونشر محتوى حي
  • 👥 نشاط المستخدم - وجود وإجراءات المستخدم في الوقت الحقيقي
  • 🔄 مزامنة البيانات - مزامنة تلقائية عبر الأجهزة

المشكلة مع الاستعلام المتكرر (الطلبات المتكررة):

// ❌ Bad - Polling every 5 seconds
setInterval(async () => {
  const orders = await Orders.getOrders();
  // Check if anything changed
  // Wastes bandwidth, delays updates, server load
}, 5000);

المشاكل:

  • 🔋 استنزاف البطارية - الطلبات المستمرة تستهلك الطاقة
  • 📡 إهدار الشبكة - معظم الطلبات تعود بـ "لا تغييرات"
  • ⏱️ تأخير التحديثات - تأخير يصل إلى 5 ثوانٍ
  • 🖥️ حمولة الخادم - طلبات غير ضرورية كل بضع ثوانٍ

حل WebSocket:

// ✅ Good - Real-time WebSocket connection
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// Subscribe to events
WS.subscribe('order.created', (order) => {
  console.log('New order received!', order);
  // Instant notification, no polling!
});

WS.subscribe('content.updated', (content) => {
  console.log('Content updated!', content);
  // Update UI immediately
});

الفوائد:

  • 🔋 فعال - اتصال دائم واحد
  • 📡 في الوقت الحقيقي - تحديثات فورية، بدون تأخير
  • ⏱️ زمن استجابة منخفض - تسليم الإشعارات في أقل من ثانية
  • 🖥️ حمولة مخفضة - الخادم يدفع فقط عند الحاجة

✨ المفاهيم الأساسية​

ما هو WebSocket؟​

WebSocket هو اتصال دائم ثنائي الاتجاه بين العميل والخادم:

  • اتصال دائم - يبقى مفتوحًا، بدون مصافحات متكررة
  • ثنائي الاتجاه - يمكن لكل من العميل والخادم إرسال الرسائل
  • في الوقت الحقيقي - تسليم الرسائل الفوري
  • معتمد على الأحداث - الاشتراك في أحداث معينة
  • فعال - تكلفة منخفضة مقارنة بالاستعلام المتكرر عبر HTTP

WebSocket مقابل الاستعلام المتكرر عبر HTTP​

الميزةWebSocketالاستعلام المتكرر عبر HTTP
الاتصالدائم (يبقى مفتوحًا)اتصالات متكررة
زمن الاستجابةأقل من ثانيةيعتمد على الفاصل الزمني (2-30 ثانية)
الكفاءةفعالة جدًامهدرة (الكثير من الاستجابات الفارغة)
حمولة الخادممنخفضة (الأحداث فقط)عالية (طلبات مستمرة)
استخدام البطاريةمنخفضمرتفع (الأجهزة المحمولة)
حالة الاستخدامتحديثات في الوقت الحقيقيمقبولة للتحديثات غير الحرجة

دورة حياة اتصال WebSocket​

1. Client connects to WebSocket server
   (WS.connect())
   ↓
2. Connection established
   (onOpen event fires)
   ↓
3. Client subscribes to events
   (WS.subscribe('event.name', callback))
   ↓
4. Server sends events when they occur
   (Instant delivery)
   ↓
5. Client receives event messages
   (Callback function executes)
   ↓
6. Connection stays open
   (No reconnection needed)
   ↓
7. Client disconnects when done
   (WS.disconnect())

أحداث WebSocket الشائعة​

نوع الحدثالوصفحالة الاستخدام المثال
order.createdتم تقديم طلب جديدعرض إشعار "طلب جديد!"
order.updatedتغيرت حالة الطلبتحديث حالة الطلب في واجهة المستخدم
content.publishedتم نشر محتوى جديدتحديث قائمة المحتوى
content.updatedتم تعديل المحتوىتحديث المحتوى المعروض
user.registeredتم تسجيل مستخدم جديدعرض مستخدم جديد في لوحة التحكم
payment.completedتم معالجة الدفعتحديث حالة الطلب إلى "مدفوع"
product.outOfStockالمنتج غير متوفرعرض شارة "غير متوفر"

لماذا تستخدم موديل WebSocket؟​

الفائدةالوصف
تحديثات في الوقت الحقيقيإشعارات فورية، بدون تأخير في الاستعلام
فعالاتصال واحد، تكلفة منخفضة
صديق للبطاريةلا استعلام مستمر على الأجهزة المحمولة
قابل للتوسعالخادم يدفع فقط عند الحاجة
مدفوع بالأحداثالاشتراك في أحداث معينة
ميزات حيةتمكين الدردشة، الإشعارات، لوحات المعلومات

🚀 مثال سريع​

📋 ما تحتاج إلى معرفته​

إدارة اتصال WebSocket​

تحتاج اتصالات WebSocket إلى إدارة دقيقة:

أفضل الممارسات:

  • تحقق من حالة الاتصال قبل الاشتراك
  • نفذ منطق إعادة الاتصال
  • تعامل مع أخطاء الاتصال بشكل جيد
  • افصل عند تسجيل خروج المستخدم

إدارة الاشتراك في الأحداث​

اشترك في الأحداث فقط بعد إنشاء الاتصال

أفضل الممارسات:

  • استخدم دوال رد نداء مسماة لتسهيل إلغاء الاشتراك
  • اشترك بعد فتح الاتصال
  • ألغ الاشتراك عند تفكيك المكون
  • لا تشترك في نفس الحدث عدة مرات

إلغاء الاشتراك في الأحداث​

قم دائمًا بإلغاء الاشتراك عند الانتهاء لمنع تسرب الذاكرة:

أفضل الممارسات:

  • ألغ الاشتراك في دوال التنظيف
  • افصل WebSocket عند عدم الحاجة
  • منع تسرب الذاكرة في التطبيقات ذات الصفحة الواحدة

استراتيجية إعادة الاتصال​

نفذ إعادة الاتصال التلقائي مع زيادة زمن الانتظار:

أفضل الممارسات:

  • استخدم زيادة زمن الانتظار لإعادة الاتصال
  • حدد الحد الأقصى لمحاولات إعادة الاتصال
  • أعد تعيين العدادات عند الاتصال الناجح
  • اسمح بفصل يدوي بدون إعادة الاتصال

هيكل حمولة الحدث​

تتبع حمولات الأحداث هيكلًا متسقًا:

أفضل الممارسات:

  • تحقق من هيكل حمولة الحدث
  • تعامل مع الحقول المفقودة بشكل جيد
  • تحقق من نوع الحمولة في TypeScript

معالجة الأخطاء​

نفذ معالجة شاملة للأخطاء:

أفضل الممارسات:

  • التقاط الأخطاء في معالجات الأحداث
  • سجل الأخطاء لأغراض التصحيح
  • عرض رسائل خطأ سهلة الفهم للمستخدم
  • لا تدع الأخطاء تتسبب في تعطل التطبيق

تحسين الأداء​

قم بتحسين أداء WebSocket:

أفضل الممارسات:

  • قم بتقليل تكرار الأحداث عالية التردد
  • اجمع تحديثات متعددة معًا
  • قم بتأخير تحديثات واجهة المستخدم
  • تجنب العمليات المكلفة في المعالجات

💡 ملاحظات مهمة​

⚠️ إدارة حالة الاتصال​

تحقق دائمًا من حالة الاتصال قبل الاشتراك

🔄 معالجة إعادة الاتصال​

يمكن أن تنقطع اتصالات WebSocket بشكل غير متوقع:

  • تغييرات الشبكة (من WiFi إلى الشبكة الخلوية)
  • إعادة تشغيل الخادم
  • انتهاء المهلة بسبب الخمول

قم دائمًا بتنفيذ منطق إعادة الاتصال

🧹 منع تسرب الذاكرة​

ألغ الاشتراك عند الانتهاء لمنع تسرب الذاكرة

🔒 الأمان​

اتصالات WebSocket مصادق عليها:

  • مصادقة قائمة على الرموز (نفس مصادقة REST API)
  • بروتوكول WebSocket الآمن (WSS)
  • لا حاجة لإرسال الرمز مع كل رسالة

أفضل الممارسات:

  • استخدم WSS (WebSocket الآمن) في الإنتاج
  • لا تكشف عن بيانات حساسة في معالجات الأحداث
  • تحقق من حمولات الأحداث قبل المعالجة

📱 اعتبارات الهواتف المحمولة​

WebSocket على الأجهزة المحمولة:

  • استخدام البطارية (فعال، ولكن اتصال دائم)
  • قد يتم إنهاء الاتصالات في الخلفية
  • تتطلب تغييرات الشبكة إعادة الاتصال

أفضل الممارسات:

  • أعد الاتصال عند عودة التطبيق إلى الواجهة
  • تعامل مع تغييرات حالة الشبكة
  • اعتبر الاستعلام للتحديثات غير الحرجة على الأجهزة المحمولة

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
connect()الاتصال بخادم WebSocketإنشاء الاتصال

❓ الأسئلة الشائعة (FAQ)​

كيف يمكنني الاتصال بخادم WebSocket؟​

استخدم WS.connect() لإنشاء اتصال. انتظر حتى يفتح الاتصال (استمع لحدث onOpen) قبل الاشتراك في الأحداث. يتم مصادقة الاتصال باستخدام رمز التطبيق الخاص بك من defineOneEntry().

ما هي الأحداث التي يمكنني الاشتراك فيها؟​

اشترك في أحداث مثل order.created، order.updated، content.published، payment.completed، user.registered، إلخ. تعتمد الأحداث المتاحة على تكوين OneEntry الخاص بك وإعدادات موديل الأحداث في لوحة الإدارة.

كيف يمكنني التعامل مع انقطاع الاتصال؟​

نفذ إعادة الاتصال التلقائي مع زيادة زمن الانتظار. استمع لأحداث onClose و onError، ثم حاول إعادة الاتصال بعد تأخير (مثل 1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، حتى 30 ثانية كحد أقصى). أعد تعيين عداد التأخير عند الاتصال الناجح.

هل يجب أن أستخدم WebSocket أم الاستعلام لتطبيقي؟​

استخدم WebSocket للميزات في الوقت الحقيقي (الدردشة الحية، الإشعارات، لوحات المعلومات) حيث تكون التحديثات الفورية مهمة. استخدم الاستعلام للتحديثات غير الحرجة أو عندما تكون اتصالات WebSocket مشكلة (جدران نارية مقيدة، وضع الخلفية على الأجهزة المحمولة).

كيف يمكنني منع تسرب الذاكرة مع اشتراكات WebSocket؟​

قم دائمًا بإلغاء الاشتراك من الأحداث عند تفكيك المكونات أو عندما لم يعد الاتصال مطلوبًا. في React، استخدم دوال التنظيف في useEffect. في Vue، استخدم دالة دورة الحياة beforeUnmount.

هل يمكنني استخدام WebSocket على الأجهزة المحمولة؟​

نعم، ولكن كن على علم بأن أنظمة تشغيل الهواتف المحمولة قد تنهي اتصالات WebSocket في الخلفية. أعد الاتصال عند عودة التطبيق إلى الواجهة. اعتبر تأثير البطارية للاتصالات الدائمة على الأجهزة المحمولة.

🎓 أفضل الممارسات​

  • تحقق من حالة الاتصال - اشترك فقط بعد فتح الاتصال
  • نفذ إعادة الاتصال - إعادة الاتصال التلقائي عند الانقطاع مع زيادة زمن الانتظار
  • ألغ الاشتراك عند التنظيف - منع تسرب الذاكرة في التطبيقات ذات الصفحة الواحدة
  • تعامل مع الأخطاء بشكل جيد - التقاط الأخطاء في معالجات الأحداث
  • قلل من تكرار الأحداث عالية التردد - تجنب إغراق واجهة المستخدم بالتحديثات
  • تحقق من حمولات الأحداث - تحقق من هيكل البيانات قبل المعالجة
  • استخدم ردود نداء مسماة - أسهل في إلغاء الاشتراك والتصحيح
  • سجل حالة الاتصال - تتبع أحداث الفتح/الإغلاق/الخطأ لأغراض التصحيح

مزيد من المعلومات حول واجهة مستخدم الموديل https://doc.oneentry.cloud/docs/events/introduction

تعريف موديل WS​

يمكنك الاشتراك في الأحداث عبر WebSocket لاستقبال الإشعارات


const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​