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

المقدمة

افتح اتصال 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(...).

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

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

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

يعيد 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() لمنع تسرب الذاكرة في تطبيقات SPA.
  • تعامل مع إعادة الاتصال - يعيد socket.io الاتصال تلقائيًا؛ خصص ذلك باستخدام disconnect / connect_error وزيادة زمنية إذا لزم الأمر.
  • تحقق من صحة حمولة الأحداث - يعتمد شكل الحمولة على مصدر الحدث؛ تحقق من الحقول قبل استخدامها.

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