دليل
التضمين الخارجي
تشرح هذه الصفحة كيفية تضمين ويدجت SRV AI Chatbot في موقع غير واجهة عملاء WHMCS الخاصة بك — مثل موقعك التسويقي الرئيسي. وهي موجّهة للمسؤولين الراغبين في إتاحة المساعد نفسه خارج WHMCS.
المتطلبات المسبقة
- يجب تفعيل Enable external-site embed بشكل عام في Settings → General (راجع الإعدادات العامة).
- تحتاج إلى مساعد موجود لتضمينه — تُضبط إعدادات التضمين لكل مساعد على حدة.
ضبط التضمين لمساعد
انتقل إلى Addons → AI Copilot Suite → Assistants → Edit على المساعد الذي تريد تضمينه. مرِّر إلى قسم External Embed (التضمين الخارجي) (متاح بمجرد حفظ المساعد مرة واحدة على الأقل).
| الاسم الودّي | الاسم النظامي | النوع | الافتراضي |
|---|---|---|---|
| تفعيل التضمين | embed_enabled |
مفتاح تبديل | معطَّل |
| المصادر المسموحة | embed_allowed_origins |
نص متعدد الأسطر، رابط مصدر كامل واحد لكل سطر | — (فارغ = حظر كل طلبات التضمين) |
| مفتاح الموقع (Site Key) | — | للقراءة فقط، قيمة سداسية عشرية مولَّدة تلقائياً من 32 حرفاً | — |
| كود التضمين | — | للقراءة فقط، وسم <script> جاهز للنسخ |
— |
Warning
المصادر المسموحة قائمة سماح صارمة، مطبَّقة من جهة الخادم: تُقبل فقط الطلبات التي يطابق مصدرها تماماً إدخالاً في هذه القائمة. إذا كانت القائمة فارغة، تُحظَر كل طلبات التضمين لهذا المساعد — وهذا افتراضي آمن.
المصدر (Origin) هو المخطط + المضيف + المنفذ لموقع، مثل https://www.example.com (وليس رابط صفحة كاملاً، ولا رمزاً بديلاً عاماً).
الحصول على كود التضمين
بمجرد تفعيل مفتاح Embed Enabled الخاص بهذا المساعد وإدراج مصدر واحد على الأقل، اضغط Save. تعرض اللوحة عندها مقتطفاً جاهزاً للنسخ يشبه:
<script src="https://your-whmcs-domain.example/modules/addons/srv_aichatbot/assets/embed.js" data-site-key="YOUR_SITE_KEY" async></script>
الصق هذا المقتطف في كود HTML لكل صفحة في الموقع الخارجي التي يجب أن يظهر فيها الويدجت (عادةً قبل وسم الإغلاق </body> مباشرة).
إعادة توليد مفتاح الموقع
اضغط Regenerate Key لإبطال المفتاح الحالي وإصدار مفتاح جديد.
Caution
تؤدي إعادة توليد المفتاح إلى تعطيل أي كود تضمين حالي يستخدم المفتاح القديم فوراً — يجب تحديث وسم <script> بـdata-site-key الجديد في كل موقع خارجي يستخدم تضمين هذا المساعد.
كيف يعمل (للمرجعية)
يقرأ السكربت المُضمَّن قيمة data-site-key الخاصة به، ويطلب إعدادات ذلك الموقع (رابط API، الثيم الأساسي، رموز Theme Studio النشط، الموضع، الإزاحات، اللغة، الأيقونة، وCSS المخصّص بعد التعقيم)، ثم يحمّل واجهة الويدجت نفسها المستخدَمة في واجهة العملاء، مقيَّدة بالموقع المسجَّل ومصادره المسموحة. خيارات المظهر تُطبَّق على التضمين كما تُطبَّق في منطقة العميل.
استكشاف الأخطاء
| المشكلة | الحل |
|---|---|
| لا يظهر الويدجت في الموقع الخارجي | تأكد من تفعيل Enable external-site embed بشكل عام (Settings → General) وتفعيل Embed Enabled لهذا المساعد تحديداً، وأن المصدر الدقيق لموقع التضمين مُدرَج في المصادر المسموحة |
| توقف الويدجت عن العمل بعد تغيير نطاق أو بروتوكول (http ← https) | حدّث المصادر المسموحة لتطابق المصدر الدقيق الجديد |
| توقف كود تضمين قديم عن العمل | على الأرجح تمت إعادة توليد مفتاح الموقع — انسخ كود التضمين الحالي وحدّث الموقع الخارجي |