كيفية إضافة روبوت الدردشة Asyntai AI إلى Docusaurus

دليل خطوة بخطوة لمواقع توثيق Docusaurus

المنصة:

الخطوة 1: احصل على كود التضمين

أولاً، انتقل إلى لوحة تحكم Asyntai وانتقل لأسفل إلى قسم "Embed Code". انسخ كود التضمين الفريد الذي سيبدو هكذا:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

ملاحظة: الكود أعلاه مجرد مثال. يجب عليك نسخ كود التضمين الفريد الخاص بك من لوحة التحكم لأنه يحتوي على معرف الأداة الشخصي الخاص بك.

الخطوة 2: إضافة البرنامج النصي إلى docusaurus.config.js (موصى به)

أفضل طريقة لإضافة روبوت الدردشة إلى جميع صفحات موقع Docusaurus هي من خلال ملف التكوين:

افتح مشروع Docusaurus في محرر الأكواد الخاص بك
حدد موقع وافتح ملف docusaurus.config.js في جذر مشروعك
ابحث عن الكائن const config = { }
أضف أو حدّث حقل scripts بأداة Asyntai الخاصة بك:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

احفظ ملف docusaurus.config.js
أعد بناء موقعك بتشغيل npm run build أو yarn build
أعد تشغيل خادم التطوير إذا كنت تعمل محلياً

نصيحة: يقبل حقل scripts مصفوفة من مصادر JavaScript. سيتم إدراج وسم script في رأس HTML لكل صفحة تلقائياً. هذه هي الطريقة الأنظف والأسهل صيانةً لمواقع Docusaurus.

الطريقة البديلة 1: تنسيق النص (صيغة أبسط)

إذا كنت تفضل نهجاً أبسط، يمكنك استخدام تنسيق النص في مصفوفة scripts:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

ملاحظة: عند استخدام تنسيق النص، ستحتاج إلى تعديل عنوان URL للسكريبت ليتضمن معرّف الأداة كمعامل استعلام، أو استخدام تنسيق الكائن الموضح في الخطوة 2 الذي يتيح لك تعيين خاصية data-asyntai-id مباشرةً.

الطريقة البديلة 2: وسوم رأس مخصصة

يمكنك أيضاً إضافة السكريبت باستخدام حقل headTags في docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

نصيحة: يوفر حقل headTags تحكماً أكبر في وسوم HTML المدرجة في قسم <head>. هذه الطريقة مكافئة وظيفياً لاستخدام حقل scripts.

الطريقة البديلة 3: قالب HTML مخصص (متقدم)

للمستخدمين المتقدمين الذين يحتاجون تحكماً كاملاً في قالب HTML:

أنشئ مجلداً جديداً: src/theme (إذا لم يكن موجوداً)
أنشئ ملفاً: src/theme/Root.js
أضف الكود التالي لحقن السكريبت ديناميكياً:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

احفظ الملف وأعد بناء موقعك

مهم: يغلف مكوّن Root.js تطبيقك بالكامل. يجب استخدام هذه الطريقة المتقدمة فقط إذا كنت بحاجة إلى منطق JavaScript مخصص أو لديك متطلبات محددة لا يمكن تلبيتها بنهج ملف الإعدادات.

الطريقة البديلة 4: تخصيص مكوّن التذييل (Swizzle)

يمكنك تخصيص التذييل ليتضمن السكريبت:

شغّل أمر التخصيص: npm run swizzle @docusaurus/theme-classic Footer -- --eject
يُنشئ هذا نسخة من مكوّن التذييل في src/theme/Footer/
عدّل مكوّن التذييل ليتضمن وسم السكريبت الخاص بك
أضف السكريبت قبل وسم إغلاق التذييل
احفظ وأعد بناء موقعك

ملاحظة: يمنحك التخصيص (Swizzling) تحكماً كاملاً في مكوّنات Docusaurus، لكنه يعني أنك ستحتاج إلى صيانة هذا المكوّن بنفسك. لن تُحدَّث المكوّنات المخصصة تلقائياً عند تحديث Docusaurus.

الخطوة 3: البناء والنشر

بعد إضافة الكود، قم ببناء ونشر موقع Docusaurus الخاص بك:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

نصيحة: أثناء التطوير، شغّل npm start أو yarn start لمعاينة تغييراتك محلياً. يجب أن يظهر روبوت الدردشة في الزاوية السفلية اليمنى في جميع الصفحات.

الخطوة 4: التحقق من التثبيت

بعد نشر تغييراتك، افتح موقع التوثيق في علامة تبويب جديدة. يجب أن ترى زر أداة الدردشة في الزاوية السفلية اليمنى. انقر عليه للتأكد من أنه يفتح ويعمل بشكل صحيح.

لا ترى الأداة؟ تأكد من إعادة بناء موقعك بعد إجراء التغييرات. تحقق من استبدال YOUR_WIDGET_ID بمعرّف الأداة الفعلي من لوحة التحكم. امسح ذاكرة التخزين المؤقت للمتصفح أو اعرض في وضع التصفح المتخفي. افتح وحدة تحكم المتصفح (F12) للتحقق من أي أخطاء JavaScript.