تثبيت الودجت

وسم سكربت واحد. بلا خطوة بناء، ولا حزمة يجب تثبيتها، ولا تكامل مع إطار عمل.

المقتطف

<script
  src="https://widget.minaya.ai/widget.js"
  data-site-key="your-site-key"
  data-api-url="https://api.minaya.ai"
  async
></script>

انسخ النسخة التي تحتوي على مفتاح موقعك الفعلي من التثبيت والتضمين في لوحة التحكم. ضعه قبل وسم الإغلاق </body>.

السمات (Attributes)

السمة	مطلوبة	الغرض
`src`	نعم	من أين يُقدَّم السكربت (شبكة CDN).
`data-site-key`	نعم	يحدد نشاطك التجاري. عام، لكنه يعمل فقط على النطاقات المُدرجة في القائمة المسموحة.
`data-api-url`	نعم	خادم Minaya الخلفي الخاص بك. منفصل عن `src` — يمكن للسكربت وواجهة API أن يعيشا على مضيفين مختلفين.
`async`	موصى به	يمنع السكربت من إعاقة عرض الصفحة.

يجب أن يشير data-api-url إلى واجهة API الخاصة بك، وليس شبكة CDN التي تقدّم السكربت. توجيهه إلى شبكة CDN ينتج 403 على كل طلب، لأن ذلك المضيف لا يملك واجهة API.

ملاحظات حول أطر العمل

Next.js

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://widget.minaya.ai/widget.js"
          data-site-key="your-site-key"
          data-api-url="https://api.minaya.ai"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

WordPress

الصق المقتطف في قالب تذييل الصفحة الخاص بالثيم، أو استخدم إضافة “header and footer scripts”. إضافته إلى ثيم فرعي (child theme) تُبقيه عبر التحديثات.

Shopify

أضفه إلى theme.liquid قبل </body> مباشرة.

تطبيقات الصفحة الواحدة (SPA)

يُثبَّت الودجت مرة واحدة ويستمر عبر التنقل من جانب العميل. لا تقم بتثبيته لكل مسار.

القائمة المسموحة للنطاقات

يعمل الودجت فقط على المصادر (origins) التي تدرجها في لوحة التحكم. أدرج كل مضيف يستخدمه الزوار:

https://example.com
https://www.example.com
https://staging.example.com

تُطابَق المصادر مطابقة تامة، لذا فإن example.com و www.example.com إدخالان مختلفان.

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

العرض	السبب
`403` على الطلبات	المصدر غير مدرج في القائمة المسموحة، أو أن `data-api-url` يشير إلى شبكة CDN.
لا يظهر شيء	لم يتم تحميل السكربت، أو أن `data-site-key` مفقود. تحقق من وحدة التحكم (console).
ألوان غير صحيحة	يُخزَّن الإعداد مؤقتًا لفترة قصيرة؛ أعد التحميل الكامل بعد حفظ التغييرات.
الودجت خلف عناصر أخرى	ارفع قيمة `z-index` الخاصة به عبر تنسيقات CSS مخصصة.

تدوير مفتاح موقعك

يؤدي التدوير إلى إبطال المفتاح القديم فورًا، وتتوقف كل عمليات التضمين الحالية عن العمل، لذا حدّث مقتطفك ضمن نفس التغيير.

السابقCSS مخصص التاليالأطر والمنصات