نظرة عامة على التضمين

كيف يعمل التضمين#

يضيف embed.js زر تشغيل ثابتاً واحداً إلى مستند الموقع المضيف. ويمكنه تحميل إطار iframe المخفي مسبقاً من https://makeagent.fast لتقييم مشغّلات الصفحة قبل النقرة الأولى؛ ويفتح الزائر المحادثة الكاملة من زر التشغيل أو من أحد المشغّلات. لا يمكن لأنماط CSS الخاصة بالموقع المضيف أن تعيد تنسيق المحادثة. ولا تُنفَّذ التغييرات على صفحة الموقع المضيف إلا عبر معالجات إجراءات الصفحة المسجّلة والمعتمدة من المالك.

المحمّل عام ولا يستخدم مفتاح API. يتم التحكم في الوصول عبر مفتاح التبديل عرضه على موقعي الخاص بالوكيل وقائمة السماح الدقيقة للأصل الأب (عناوين المواقع المسموح بها). المعرّف المختصر للموقع (site slug) مجرد معرّف وليس سراً.

المتطلبات الأساسية#

قبل نسخ الشيفرة:

1. أنشئ وكيلاً واختبره في لوحة التحكم.
2. استخدم المقتطف الذي يولّده الوكيل؛ فتفعيل رابط الوكيل المنفصل الخاص به ليس مطلوباً.
3. في صفحة الوكيل الخاصة بالوكيل، افتح انشره ← أداة الموقع. إذا لم تكن الأداة مفعّلة بعد، فاختر تفعيل التضمين؛ ثم تأكد من تشغيل عرضه على موقعي.
4. ضمن عناوين المواقع المسموح بها، أضف كل أصل أب (origin) سيعرض زر التشغيل.
5. اختر حفظ إعدادات التضمين، ثم انسخ المقتطف المولَّد.

يتكوّن الأصل (origin) من المخطط (scheme) واسم المضيف (hostname) ومنفذ اختياري فقط، ولا يحتوي أبداً على مسار. هذه أربعة أصول مختلفة ويجب إضافة كل منها على حدة عند استخدامها:

https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000

لا تُدخل https://example.com/pricing ولا *.example.com ولا أي حرف عام (wildcard) في النهاية. إذا كان موقع الإنتاج يعيد التوجيه من النطاق المجرّد إلى www، فأضف إلى قائمة السماح الأصل الذي يبقى في شريط عنوان المتصفح بعد إعادة التوجيه.

تثبيت المحمّل#

ضع نصاً برمجياً واحداً قبل وسم الإغلاق </body>، أو استخدم دورة الحياة الخاصة بالمتصفح فقط التي يوصي بها دليل إطار العمل لديك.

تنسخ ورقة أداة الموقع (صفحة الوكيل ← انشره) هذه الصيغة (المعرّف المختصر للموقع، والموضع، والتسمية الاختيارية، ومعامل كسر التخزين المؤقت ?v=). أبقِ على async. وأبقِ على معامل الاستعلام ?v= من المقتطف حتى لا تثبّت المواقع المضيفة محمّلاً قديماً.

<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>

السمة data-agent وحدها مطلوبة. وفيما يلي السمات الاختيارية التي يقرؤها المحمّل فعلاً:

<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>

لا تضع مفتاح API الخاص بـ MAF، ولا مفتاح مزوّد، ولا رمز موصّل، ولا هوية زائر، ولا بيانات عملاء خاصة في أي سمة data-*. ولا تخترع سمات مثل data-api-key أو data-z-index أو data-offset أو data-delay. أما data-maf-bootstrapped فيضبطها المحمّل نفسه.

ضبط السمات#

تُقرأ من وسم embed.js فقط. ويقبل الـ iframe ألوان التمييز بصيغة hex فقط.

يستخدم الجذر المولَّد أيضاً data-maf-open داخلياً لتتبّع ما إذا كانت المحادثة مفتوحة. وهي ليست إعداداً في وسم النص البرمجي ولا أمراً عاماً لفتح الأداة. راجع المتابعات لمعرفة سلوك المشغّلات.

في غياب data-theme، يأخذ المحمّل عيّنة من خلفية الموقع المضيف ثم يعود إلى تفضيل نظام تشغيل الزائر. كما يمرّر عائلة خط الموقع المضيف إلى الإطار ويجلب أحدث مظهر لزر التشغيل. ولا يمنع فشل طلب المظهر ظهور زر التشغيل؛ إذ يحتفظ بالنمط الافتراضي الآمن. وتؤدي تغييرات العرض في لوحة التحكم إلى تحديث هذا الجلب دون إعادة نشر الموقع.

سلوك وقت التشغيل#

• حمّل النص البرمجي مرة واحدة لكل مستند. تكرار المعرّف المختصر نفسه آمن (idempotent) ولا ينتج إلا جذراً واحداً هو maf-embed-root-YOUR_SITE_SLUG.
• يمكن لوكلاء مختلفين التعايش في مستند واحد. يضع المحمّل علامة data-maf-bootstrapped على كل نص برمجي عولج، بحيث يهيّئ الاحتياطي غير المتزامن كل وسم data-agent مختلف مرة واحدة بالضبط.
• يمكن تحميل الـ iframe مسبقاً من أجل مشغّلات الصفحة. ويظل مخفياً إلى أن يظهر أحد المشغّلات أو يفتح الزائر المحادثة؛ أما الجلسات التي استخدمت مشغّلاً من قبل فتحتفظ بمسار الفتح الكسول. ويبقى الميكروفون والتشغيل التلقائي والكتابة في الحافظة خاضعة لنموذج أذونات الـ iframe في المتصفح.
• في تطبيق يعتمد التوجيه من جهة العميل، ركّب المحمّل في أعلى تخطيط (layout) ينبغي أن يملكه حتى لا تعيد تغييرات المسار تحميل المحادثة.
• إزالة عنصر النص البرمجي وحده لا تزيل زر تشغيل أُنشئ بالفعل. وللتفكيك الخاص بمسار معيّن، أزل أيضاً العنصر المطابق maf-embed-root-.... وأعد تحميل النص البرمجي بعد التفكيك لتركيبه من جديد.
• يتبادل الإطار والمحمّل رسائل ذات مساحة أسماء تخص دورة الحياة والهوية والمشغّلات وإجراءات الصفحة. ويرفض المحمّل الرسائل التي لا تأتي من أصل Make Agent Fast ومن المعرّف المختصر الحالي للموقع.

التحقق من التثبيت#

اختبر الصفحة المنشورة، لا معاينة محرّر منشئ المواقع فقط:

1. افتح عنوان URL المنشور في نافذة خاصة وتأكد من أن أصله الدقيق مضاف إلى قائمة السماح.
2. تأكد من أن https://makeagent.fast/embed.js?v=20261022-open يعيد 200 في لوحة الشبكة (Network).
3. تأكد من وجود عنصر واحد فقط يحمل data-maf-embed="YOUR_SITE_SLUG".
4. افتح زر التشغيل وتأكد من نجاح طلب الـ iframe إلى /embed/YOUR_SITE_SLUG.
5. أرسل سؤالاً واقعياً وتأكد من ظهوره في المحادثات.
6. اختبر نافذة عرض ضيقة للجوال، واختبر إذن الميكروفون إن كان مفعّلاً.

تشخيص اختفاء زر التشغيل#

اختيار دليل التثبيت#

استخدم HTML وJavaScript للوسم البرمجي العادي. وبالنسبة إلى React وVue وSvelteKit وAstro وWordPress وShopify وWebflow وFramer وWix وSquarespace أو Ghost، اختر الدليل المطابق في الشريط الجانبي. أما المنصات التي لا تسمح بشيفرة JavaScript اعتباطية، مثل كثير من واجهات Notion وLinktree، فيمكنها الإحالة إلى رابط الوكيل الخاص بالوكيل — وهو صفحة محادثة عامة واحدة على عنوان الوكيل نفسه، تُفعَّل في الخطوة الأخيرة من الإعداد الأولي (جرّبه على هاتفك) وفي تبويب العرض بصفحة الوكيل. ومن الخيارات الأخرى موقع أحد العملاء الذي يتضمن التضمين.

لوكلاء البرمجة#

هل تثبّت هذا على موقع أحد العملاء باستخدام Claude Code أو Cursor أو Codex؟ انسخ skills/embed-agent/SKILL.md من مستودع Make Agent Fast إلى .cursor/skills/embed-agent/ أو .claude/skills/embed-agent/. هذا الملف هو وصفة التثبيت (السمات وCSP والموضع). وتبقى هذه الصفحة الدليل المخصص للبشر.