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

المقدمة

افتح اتصال WebSocket في الوقت الحقيقي لتلقي المحتوى، وتحديثات الطلب، وتحديثات المستخدم دون الحاجة للاستعلام.

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

🎯 ماذا تفعل هذه الوحدة؟​

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

تفتح الطريقة الوحيدة، connect(), الاتصال وتعيد Socket من socket.io. إنها متزامنة و تتطلب مستخدمًا مصرحًا به، لذا قم بالمصادقة أولاً.

🚀 البدء السريع​

قم بتهيئة الوحدة من defineOneEntry:


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

connect() متزامنة وتعيد Socket من socket.io (بدون await). قم بإرفاق معالجات الأحداث باستخدام socket.on(...):

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

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

ما هو WebSocket؟​

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

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

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

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

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

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect when done: socket.disconnect()

ما هي الأحداث التي تصل عبر الاتصال​

لا يوجد كتالوج ثابت لأسماء أحداث SDK. يتم تشغيل الأحداث وفقًا لتكوين وحدة الأحداث الخاصة بك في لوحة الإدارة (يجب أن يكون الخيار WebSocket مفعلًا). تستمع لحدث بواسطة علامته باستخدام socket.on('<event_marker>', callback).

تعتمد الحمولة على مصدر الحدث. الحقول النموذجية للحمولة (انظر connect() للحصول على أمثلة كاملة):

حقل الحمولةيصل لـيحتوي على
attributesكل حدثسمات الحدث نفسه
productأحداث الكتالوج (المنتج)سمات المنتج بالإضافة إلى title
userأحداث نموذج المستخدمالحقول من نموذج المستخدم
orderأحداث الطلبid الطلب والسمات
email / codeنماذج التسجيل / الكودحقول إضافية من النموذج

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

المصادقة مطلوبة​

تتطلب connect() مستخدمًا مصرحًا به — اتصل بـ AuthProvider.auth(...) قبل الاتصال. يتم مصادقة الاتصال باستخدام رمز وصول المستخدم بالإضافة إلى رمز تطبيقك من defineOneEntry(). إذا لم يكن هناك مستخدم مصرح به، يسجل SDK خطأ.

connect() متزامنة​

تعيد connect() Socket من socket.io على الفور — لا تقم بـ await لها. انتظر حدث connect قبل الاعتماد على المقبس، ثم قم بإرفاق المعالجات باستخدام socket.on(...).

يتم تحميل socket.io عند الطلب​

يتم استيراد socket.io-client (~41 كيلوبايت) في المرة الأولى التي يتم فيها استدعاء connect()، لذا فإن المشاريع التي لا تفتح مقبسًا لا تقوم بشحنه — انظر حجم الحزمة وصيغ الوحدات.

التوقيع غير متغير والاستخدام العادي غير متأثر: حتى يتم حل الجزء، يقوم الكائن المعاد بتجميع أي شيء تفعله به (on, emit, disconnect) ويعيد تشغيله على المقبس الحقيقي في نفس الدورة التي تم إنشاؤه فيها — قبل أن يتمكن الاتصال من تسليم أي شيء — لذا لا يتم فقدان أي حدث. قراءة الحالة مبكرًا دقيقة أيضًا: المقبس الذي تم إنشاؤه حديثًا غير متصل أيضًا، لذا فإن id هو undefined و connected هو false.

الفرق الوحيد: لا يمكن لطريقة يجب أن ترجع قيمة (مثل listeners()) أن تجيب قبل وصول الجزء، والأشياء المتداخلة مثل socket.io يمكن الوصول إليها فقط بمجرد تحميلها.

اشترك بعد فتح الاتصال، ونظف عند الانتهاء​

قم بإرفاق معالجات الأحداث بعد أن يتم تشغيل حدث connect، وقم بفصلها (socket.off) بالإضافة إلى استدعاء socket.disconnect() عندما لم يعد الاتصال مطلوبًا (مثل عند إلغاء تحميل المكون أو تسجيل خروج المستخدم) لمنع تسرب الذاكرة في تطبيقات الصفحة الواحدة.

إعادة الاتصال​

يعيد socket.io الاتصال تلقائيًا بشكل افتراضي. لتخصيص ذلك، استمع لأحداث disconnect و connect_error وأعد الاتصال مع زيادة زمنية، مع إعادة تعيين التأخير عند نجاح connect.

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

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

🔐 تتطلب connect() مستخدمًا مصرحًا به — قم بالمصادقة أولاً عبر AuthProvider. بعد الاتصال، قم بإرفاق معالجات الأحداث باستخدام socket.on(...).

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

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

استخدم WS.connect() لفتح اتصال — إنه متزامن ويعيد Socket من socket.io. يتطلب مستخدمًا مصرحًا به، لذا اتصل بـ AuthProvider.auth(...) أولاً. انتظر حدث connect قبل الاعتماد على المقبس، ثم قم بإرفاق المعالجات باستخدام socket.on('<event_marker>', callback).

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

لا توجد قائمة ثابتة لأحداث SDK. يتم تعريف الأحداث بواسطة تكوين وحدة الأحداث الخاصة بك في لوحة الإدارة (مع تفعيل خيار WebSocket)، وتستمع لحدث بواسطة علامته باستخدام socket.on('<event_marker>', callback). انظر connect() للحصول على أمثلة على الحمولة (المنتج، المستخدم، الطلب، النموذج).

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

يعيد socket.io الاتصال تلقائيًا بشكل افتراضي. لتخصيص ذلك، استمع لأحداث disconnect و connect_error وأعد الاتصال مع زيادة زمنية (مثل 1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، حتى حد أقصى)، مع إعادة تعيين عداد التأخير عند نجاح connect.

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

افصل معالجات الأحداث (socket.off) واستدعِ socket.disconnect() عندما يتم إلغاء تحميل المكونات أو لم يعد الاتصال مطلوبًا. في React، قم بذلك في تنظيف useEffect؛ في Vue، في beforeUnmount.

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

  • قم بالمصادقة أولاً - تتطلب connect() مستخدمًا مصرحًا به.
  • لا تنتظر connect() - إنها متزامنة وتعيد Socket.
  • اشترك بعد فتح الاتصال - قم بإرفاق المعالجات بعد تشغيل حدث connect.
  • نظف - افصل المعالجات (socket.off) و socket.disconnect() لمنع تسرب الذاكرة في تطبيقات الصفحة الواحدة.
  • تعامل مع إعادة الاتصال - يعيد socket.io الاتصال تلقائيًا؛ خصص ذلك باستخدام disconnect / connect_error وزيادة زمنية إذا لزم الأمر.
  • تحقق من صحة حمولة الأحداث - شكل الحمولة يعتمد على مصدر الحدث؛ تحقق من الحقول قبل استخدامها.

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