انتقل إلى المحتوى

أداة الويب وكود التضمين

المسار: /dashboard/embed · الصلاحية: وحدة الإعدادات

Widget & Embed Widget & Embed

تعد أداة الويب (Widget) هي الوسيلة الأساسية التي يتفاعل من خلالها المستخدمون مع مساعد الذكاء الاصطناعي الخاص بك على موقعك الإلكتروني. تشرح هذه الصفحة كيفية نشر الأداة، ووظيفة كل سمة من سمات التضمين، وكيفية عمل الأداة تقنياً.

الحصول على كود التضمين الخاص بك

أسهل طريقة للحصول على كود التضمين هي:

  1. انتقل إلى لوحة التحكم (Dashboard) ← التضمين (Embed) في الشريط الجانبي.
  2. تقوم الصفحة تلقائياً بإنشاء السكريبت الصحيح للبوت الحالي والنطاق (Domain) الخاص بك.
  3. انقر على نسخ (Copy) لنسخ مقتطف التضمين بالكامل.
  4. قم بلصقه في كود HTML الخاص بموقعك، مباشرة قبل وسم الإغلاق </body>.

مرجع سكريبت التضمين

<script 
  src="https://user.frenzy.bot/chatbot-widget/v1/js/loader.js"
  data-bot-id="sales-assistant"
  data-bot-name="Sales Assistant"
  data-theme-color="#3b82f6"
  data-backend-url="https://user.frenzy.bot"
  async>
</script>

السمات (Attributes)

السمة مطلوبة وظيفتها
data-bot-id نعم المعرف الفريد (Slug ID) للبوت الخاص بك.
data-bot-name لا الاسم الذي يظهر في أعلى نافذة الدردشة.
data-theme-color لا اللون الأساسي للأداة (كود هيكس - hex code).
data-backend-url لا عنوان URL للخادم التقني. القيمة الافتراضية هي https://user.frenzy.bot (أو نطاقك المخصص).

كيفية العثور على معرف البوت (Bot ID)

  • افتح لوحة التحكم وانتقل إلى التضمين أو الإعدادات.
  • يتم عرض معرف البوت في كود التضمين وفي صفحة إدارة البوتات.
  • التنسيق: أحرف وأرقام صغيرة مع شرطات (مثال: sales-assistant أو support-bot).

صفحة التضمين الديناميكية

تقوم صفحة لوحة التحكم ← التضمين بالكشف التلقائي عن اسم المضيف الحالي وإنشاء مقتطف التضمين الصحيح. هذا الإجراء أكثر أماناً من كتابة الروابط يدوياً للأسباب التالية:

  • إذا قمت بتغيير النطاقات لاحقاً، فسيعكس كود التضمين المُنشأ النطاق الجديد تلقائياً.
  • يحصل كل بوت على مقتطف تضمين خاص به مع المعرف الصحيح data-bot-id.
  • ميزة النسخ بنقرة واحدة تجعل عملية النشر سريعة للغاية.

مميزات أداة الويب

تم بناء أداة FRENZY.BOT للاستخدام في بيئات العمل الإنتاجية بالمميزات التالية:

الميزة وظيفتها
عزل Shadow DOM يمنع تنسيقات CSS الخاصة بموقعك من التأثير على تصميم الأداة
استمرارية الجلسة يحافظ على سجل الدردشة حتى بعد تحديث الصفحة عبر localStorage
التحميل البطيء (Lazy loading) يمنع بطء الأداء في المحادثات الطويلة
نافذة السياق ترسل آخر 6 رسائل للذكاء الاصطناعي لضمان جودة الاستجابة
متعددة اللغات تدعم لغات متعددة مع خاصية الكشف التلقائي
دعم RTL دعم كامل للتخطيط من اليمين إلى اليسار للغتين العربية والعبرية
الأسئلة المقترحة مطالبات مكتوبة مسبقاً تظهر أسفل رسالة الترحيب
نموذج جذب العملاء التقاط بيانات الاتصال داخل الدردشة مع حقول قابلة للتخصيص
تحويل النص إلى كلام تشغيل صوتي اختياري لردود الذكاء الاصطناعي

اختبار أداة الويب

قبل إضافة الأداة إلى موقعك الفعلي:

  1. تأكد من أن الخادم يعمل.
  2. افتح صفحة الاختبار المدمجة: https://user.frenzy.bot/chatbot-widget/test.html
  3. أرسل بضع رسائل تجريبية.
  4. قم بتحديث الصفحة — يجب أن يظل سجل الدردشة موجوداً.
  5. تحقق من أن البوت يجيب باستخدام محتوى قاعدة المعرفة الخاصة بك.

Integration مع ووردبريس (WordPress)

بالنسبة لمواقع ووردبريس، يتوفر خياران:

الخيار الأول: لصق السكريبت

أضف سكريبت التضمين إلى ملف footer.php الخاص بالقالب، أو استخدم إحدى الإضافات (plugins) التي تتيح إضافة أكواد مخصصة في التذييل.

الخيار الثاني: إضافة ووردبريس

  • قم برفع ملف ZIP الخاص بإضافة FRENZY.BOT لووردبريس وقم بتفعيلها.
  • استخدم الكود القصير [FRENZY.BOT_whitelabel] لإنشاء صفحة بوابة دعم مدمجة بملء الشاشة.

أخطاء شائعة

المشكلة السبب الحل
الأداة تظهر ولكن لا تجيب معرف data-bot-id خاطئ تحقق من معرف البوت في لوحة التحكم ← التضمين
الأداة لا تظهر نهائياً تعذر الوصول للخادم تأكد من فتح المنفذ 8321 وأن الخادم يعمل
تعمل على localhost وتفشل في الموقع الفعلي فقدان data-backend-url قم بتعيينه ليكون رابط نطاق موقعك الفعلي
تعارض CSS مع موقعك عدم استخدام Shadow DOM لا ينبغي حدوث ذلك — تحقق من وجود تنسيقات عامة قسرية
ظهور إصدار قديم من الأداة ذاكرة التخزين المؤقت للمتصفح يقوم نظام معالجة ذاكرة التخزين المؤقت المستند للإصدار بحل ذلك تلقائياً

تضمين لكل بوت على حدة

في إعدادات البوتات المتعددة، يمتلك كل بوت مقتطف تضمين خاصاً به. تحدد سمة data-bot-id أي بوت سيتولى المحادثة. تستخدم أداة كل بوت ما يلي بشكل مستقل:

  • التوجيه الأساسي (System prompt) ونموذج الذكاء الاصطناعي.
  • الهوية البصرية، الألوان، والصورة الرمزية (Avatar).
  • رسالة الترحيب والأسئلة المقترحة.
  • إعدادات نموذج جذب العملاء.
  • إعدادات اللغة.

قم بالتبديل بين البوتات في لوحة التحكم لإنشاء كود التضمين الصحيح لكل منها.

الأسئلة الشائعة

س: الأداة يتم تحميلها ولكن لا يوجد رد.

  • تأكد من صحة معرف data-bot-id.
  • تأكد من اتصال OpenRouter (يجب أن يكون مؤشر LLM باللون الأخضر).
  • تحقق من أن قاعدة المعرفة تحتوي على محتوى.

س: الأداة تعمل على localhost ولكن ليس في الموقع الفعلي.

  • تأكد من فتح المنفذ 8321 على خادمك.
  • قم بتعيين data-backend-url إلى رابط نطاقك الفعلي (مع https://).
  • إذا كنت تستخدم نطاقاً مخصصاً، فتأكد من تكوين شهادة SSL بشكل صحيح.

س: هل يمكنني استخدام الأداة على عدة نطاقات؟

  • نعم. تعمل الأداة على أي نطاق طالما أن data-backend-url يشير إلى خادمك. استخدم صفحة التضمين الديناميكية أو النطاق المخصص لضمان الاستمرارية.

س: كيف أقوم بتحديث الأداة بعد إجراء تغييرات؟

  • يتم تطبيق تحديثات الأداة تلقائياً عبر نظام معالجة ذاكرة التخزين المؤقت. عند تحديث الخادم، يرتفع إصدار الأداة وتقوم المتصفحات بجلب النسخة الجديدة تلقائياً.