Vue وNuxt

تجهيز التضمين#

فعّل خيار Show it on my website للـ agent (صفحة الـ agent ← Put it live ← Website widget)، وأضف الأصل (origin) الدقيق لبيئات التطوير المحلي والمعاينة والإنتاج ضمن Allowed website addresses. وحدِّد ما إذا كان الـ agent سيخدم التطبيق بأكمله أم مكوّنات مسارات محددة فقط.

إضافة Nuxt على مستوى الموقع#

أنشئ إضافة بصيغة .client.ts حتى لا يُنفَّذ أي كود يتعامل مع DOM أثناء العرض على الخادم. يحمّلها Nuxt مرة واحدة في المتصفح، مما يُبقي زر الفتح والمحادثة مستقرَّين أثناء التنقل داخل جانب العميل.

// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "Ask us";
  script.async = true;
  document.body.appendChild(script);
});

لا تضع أي سرّ في runtimeConfig.public؛ فالمعرّف العام للموقع (site slug) والإعدادات المرئية فقط هي ما يجوز أن يصل إلى المتصفح. أما مفاتيح MAF API ومفاتيح المزوّدين الحقيقية فتبقى في إعدادات التشغيل الخاصة بالخادم.

لا تتضمن الإضافة على مستوى الموقع تنظيفًا عند إلغاء التركيب عمدًا، لأنها ترتبط بدورة حياة تطبيق Nuxt. أثناء استبدال الوحدات الفوري (HMR) في بيئة التطوير، قد يبقى الجذر السابق إلى أن تعيد تحميل الصفحة بالكامل؛ ويمنع فحص الجذر ظهور زر فتح ثانٍ. تحقّق من السلوك النهائي باستخدام نسخة إنتاج نظيفة بدلًا من تعديل الإضافة مرارًا في علامة تبويب واحدة طويلة العمر.

مكوّن Vue خاص بمسار محدد#

للمسارات المحددة، ثبّت الأداة في onMounted واحذف السكربت والجذر المُنشأ في onBeforeUnmount.

<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>

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

إذا بدّل تطبيق Vue بين مستأجرين (tenants) مصادَقين دون إعادة تحميل كاملة للصفحة، فتعامل مع ذلك على أنه إزالة وإعادة تركيب صريحتان. احذف جذر المعرّف (slug) القديم، وتحقّق من المعرّف العام للمستأجر الجديد اعتمادًا على حالة تطبيق موثوقة، ثم أضف سكربتًا جديدًا. تغيير script.dataset.agent بعد تشغيل أداة التحميل لا يعيد توجيه الـ iframe الموجود.

تظل ترويسات الأمان الخاصة بالموقع المضيف سارية على مخرجات Nuxt/Vue. أضف أصل أداة التحميل والإطار إلى CSP، واسمح بالميكروفون فقط عند تفعيل الصوت؛ فالإضافة التي تعمل في جانب العميل فقط لا يمكنها تجاوز سياسة المتصفح المحددة على مستوى الاستجابة.

التحقق من SSR والتوجيه#

1. شغّل نسخة الإنتاج من Nuxt/Vue وتأكد من عدم ظهور الخطأ document is not defined.
2. حمّل مباشرةً مسارًا يحتوي على التضمين وتأكد من وجود جذر واحد.
3. تنقّل داخل جانب العميل وتأكد من السلوك المطلوب: على مستوى الموقع أو على مستوى المسار.
4. افحص embed.js وiframe وCSP والأصل (origin) الدقيق.
5. أرسل رسالة واختبر السلوك على الجوال والميكروفون.

استكشاف الأخطاء وإصلاحها#

لا يوجد حاليًا محوّل npm منشور لـ Vue/Nuxt؛ يستخدم هذا الدليل أداة التحميل المستضافة المدعومة مباشرةً.