ثبّت الويدجت

ويدجت RolChat زر عائم واحد يتكيف مع الوحدات التي فعّلتها: الدردشة، ونموذج طلب معاودة الاتصال، وحجز الاجتماعات، ونموذج العملاء المحتملين، والبحث في قاعدة المعرفة، كلها داخله. ثبّته مرة واحدة؛ أما ما يعرضه فيُحدَّد من لوحة التحكم.

1. انسخ المقتطف

في الإعدادات ← الويدجت، اختر الموقع وانسخ مقتطف التثبيت. يبدو هكذا:

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

مفتاح الويدجت عام وآمن لوضعه في الصفحة. فهو يسمّي موقعك وموقّع، فلا يستطيع أحد توجيه نسخة من الويدجت إلى حسابك. تضيف لوحة التحكم مفاتيح أخرى إلى الكائن (التحية، وعنوان الترويسة، والسمة، وساعات العمل، والتخطيط لكل حجم شاشة) كلما غيّرت إعدادات الويدجت؛ انسخ المقتطف مجددًا بعد تغييرها، أو اترك الكائن في حده الأدنى ودع الويدجت يجلب الباقي.

حجم stub.js بضعة كيلوبايتات، ولا يحمّل الباقي إلا عندما يحتاجه الزائر: واجهة الدردشة عند أول فتح، والتتبع بعد الموافقة، وشريط الموافقة حيث يكون مطلوبًا.

2. الصقه قبل `</body>`

أضف المقتطف إلى كل صفحة تريد فيها الويدجت، ويُفضَّل عبر قالب موقعك أو مدير الوسوم ليظهر في كل مكان دفعة واحدة. يُحمَّل السكربت بشكل غير متزامن ولا يعيق العرض؛ وحزمة التحميل الأول صغيرة عمدًا كي لا تؤثر في مؤشرات Core Web Vitals لديك.

3. تحقق من أنه يعمل

افتح موقعك في نافذة خاصة. يظهر الزر في الزاوية التي اخترتها. في لوحة التحكم، يعرض قسم الزوار الجلسة المجهولة الجديدة لحظيًا، وتظهر الرسالة المرسلة من الويدجت في صندوق الوارد كمحادثة جديدة.

تعريف المستخدمين المسجّلين

إذا كان زوارك يسجّلون الدخول إلى منتجك، فأخبر RolChat بهويتهم لتُربط المحادثات بجهة الاتصال الصحيحة:

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

السمات المقبولة هي email وphone وfirst_name وlast_name وexternal_id وكائن custom_fields مسطّح؛ ويُتجاهل أي شيء آخر. يبحث RolChat عن البريد الإلكتروني في CRM. إذا وُجدت جهة اتصال، تُربط الجلسة بها ويرى الوكيل الملف؛ وإن لم توجد، تُحفظ البيانات ويُنشأ عميل محتمل عندما يكتب الزائر لأول مرة.

لمستوى ثقة أعلى، يمكن للواجهة الخلفية لديك توقيع الهوية: مرّر التوقيع الذي يصدره RolChat للمستخدم مع السمات، ولن تُرقّى الجلسة إلا إذا تحقق التوقيع. استدعِ window.rolchat.reset() عند تسجيل خروج المستخدم، وإلا سيرى الشخص التالي على ذلك المتصفح المحادثة السابقة.

واجهة JavaScript API

يتوفر window.rolchat بمجرد تشغيل الـ stub؛ الاستدعاءات التي تتم قبل تحميل الحزمة توضع في قائمة انتظار وتُنفّذ بالترتيب.

الطريقة	ما تفعله
`show()` / `hide()`	إظهار زر التشغيل أو إخفاؤه
`open()` / `close()`	فتح لوحة الدردشة أو إغلاقها
`identify(traits)`	ربط الجلسة بشخص (أعلاه)
`reset()`	نسيان الهوية وبدء جلسة مجهولة جديدة
`pushEvent(name, props)`	الإبلاغ عن حدث مخصص لرسائل التشغيل والأتمتة
`trackPageView(path?)`	الإبلاغ عن مشاهدة صفحة في تطبيقات الصفحة الواحدة
`setLocale(code)`	تبديل لغة الويدجت
`showConsentPreferences()`	فتح مركز تفضيلات الموافقة
`on(event, handler)` / `off(event, handler)`	الاشتراك في `chat:opened` و`chat:closed` و`message:sent` و`message:received` و`session:started`

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

اللغة واتجاه الكتابة

يتحدث الويدجت باللغة التي تثبّتها بالخيار lang في window.rolchatConfig (مثلًا "lang": "de")؛ وبدونه يستخدم لغة متصفح الزائر بحسب ترتيب تفضيلات المتصفح، مختارًا من بين 40 لغة يدعمها RolChat؛ وإن لم تتطابق أي لغة فالإنجليزية. لا يُستخدم إعداد لغة الموقع نفسه: لكي يتحدث الويدجت بلغة موقعك اضبط lang. تُعرض العربية والعبرية من اليمين إلى اليسار. لا يترجم الويدجت رسائل الوكلاء؛ ويمكن لجهة الوكيل استخدام الترجمة الفورية بالذكاء الاصطناعي بدلًا من ذلك.

ملفات تعريف الارتباط والموافقة

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

أين يُضبط الويدجت

ماذا	أين
الألوان، والموضع، والتحية، ونقاط الدخول، ومقتطف التثبيت	الإعدادات ← الويدجت
الوحدات التي تظهر داخل الويدجت	الإعدادات ← الوحدات (لكل موقع)
ساعات العمل ورسالة عدم التواجد	الإعدادات ← المواقع ← ساعات العمل
رسائل التشغيل المعروضة في صفحات محددة	التسويق ← المشغّلات