الزوّار المُوثَّقون (هوية JWT)

افتراضيًا يكون زوّار الدردشة مجهولين. إذا كان موقعك أو تطبيقك يملك تسجيل دخول خاصًا به، يمكنك نقل تلك الهوية إلى الدردشة: يوقّع خادمك رمز JWT صغيرًا للمستخدم المسجّل، ويقدّمه الودجت مرة واحدة، فترتبط المحادثة بذلك المستخدم — نفس السجل على كل الأجهزة، دون إعادة تحقق، ويرى وكلاؤك مع من يتحدثون.

أوضاع التوثيق

افتح التكاملات ← الموقع ← تكاملك ← التوثيق:

الوضع	السلوك
زوّار مجهولون	يمكن لأي شخص المحادثة. يمرّ الزوّار بفحص الروبوتات (Cloudflare Turnstile). الافتراضي.
مجهول + مُوثَّق	يُسمح للزوّار المجهولين؛ ويُتعرَّف على حاملي JWT صالح كمستخدمين مسجّلين.
مُوثَّق فقط	لا يمكن المحادثة إلا بحمل JWT صالح — للتطبيقات خلف تسجيل دخولك.

فرض الهوية (مفيد فقط في مجهول + مُوثَّق): عند تفعيله، يُرفض الزائر الذي يقدّم JWT غير صالح أو منتهي الصلاحية بدلًا من الرجوع إلى جلسة مجهولة.

مفتاح التوقيع

يدير قسم التوثيق مفتاح توقيع خاصًا بكل تكامل:

• إنشاء — يُعرض المفتاح مرة واحدة. انسخه إلى مدير أسرار خادمك.
• تدوير — يصدر مفتاح جديد؛ ويبقى السابق صالحًا 24 ساعة لتتمكن خوادمك من الانتقال دون انقطاع.
• إلغاء — يتوقف المفتاحان فورًا. إذا كان التكامل يتطلب التوثيق فيعود إلى الوضع المجهول.

وقِّع على خادمك فقط

يجب ألا يظهر المفتاح أبدًا في جافاسكربت الموقع أو داخل تطبيق جوال أو أي كود على جهة العميل. أنشئ الرموز في خادمك وسلّم JWT الجاهز فقط للعميل.

إنشاء JWT (في خادمك)

وقّع رمز HS256 بمفتاح التكامل:

// Node.js — npm i jsonwebtoken
const jwt = require('jsonwebtoken');

const orkiUserJwt = jwt.sign(
  {
    sub: user.id,                       // معرّف المستخدم الثابت لديك (يصبح هوية المحادثة)
    tenantId: '<معرّف المستأجر>',
    integrationId: '<معرّف التكامل>',
    name: user.name,                    // اختياري — يملأ ملف العميل مسبقًا
    email: user.email,                  // اختياري
  },
  process.env.ORKI_WEBCHAT_SIGNING_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' },  // exp إلزامي؛ الحد الأقصى 24 ساعة
);

المطالبات الإلزامية: sub وiat وexp (≤ 24 ساعة) وtenantId وintegrationId — ويجب أن يطابق الأخيران التكامل الذي سيُستخدم معه الرمز.

استخدام الرمز

تضمين الموقع:

webchat('init', { tenantId, integrationId, userJwt: orkiUserJwt });
// لاحقًا، قبيل انتهاء الصلاحية — دون إعادة تحميل:
webchat('updateToken', { userJwt: freshJwt });
// عند تسجيل الخروج:
webchat('logout');

تطلق الصفحة حدث webchat:auth-required عندما يحتاج الودجت رمزًا (جديدًا)، و webchat:user-set / webchat:auth-error بعد كل محاولة.

React (‏@orki/webchat-react): مرّر userJwt إلى <OrkiWebChat />، أو استخدم useOrkiWebChat().setUser / updateToken / logout.

تطبيقات الجوال: راجع حِزم React Native وFlutter.

واجهة دردشة مخصصة: راجع واجهة برمجة دردشة العملاء.

كيف يعمل (وما لا يفعله أبدًا)

يُقدَّم JWT مرة واحدة عند بدء الجلسة. يتحقق Orki من التوقيع بمفتاح تكاملك ثم يصدر اعتمادًا قصير الأمد خاصًا به — لا يظهر رمزك أبدًا في عناوين URL ولا يسافر مع رسائل الدردشة. يتجاوز الزائر المُوثَّق فحص الروبوتات (توقيع خادمك إشارة أقوى من الكابتشا). وإذا سجّل زائر مجهول دخوله أثناء المحادثة، تُرقّى محادثته الحالية إلى الهوية المُوثَّقة مع الحفاظ على السجل.