وثائق Amargi Widget

آخر تحديث: 2026-05-29

نظرة عامّة

Amargi Widget هو سطح التضمين بمقتطف واحد لمجموعة Amargi. كل "Publication" تربط مصدراً (وكيل Agents، أو قناة Reach Webchat، أو نموذج/قاعدة معرفة Escalate) بثيمة واجهة (Classic / Modern / Minimal) ومفتاح عام (wid_…). الصق وسم <script> على موقعك، وستظهر فقاعة الدردشة الجاهزة.

الحزمة تخدم كلها من نطاق Amargi، حوالي 40 كيلوبايت لكل ثيمة (مضغوطة)، تُحمَّل من مزوّد CDN Amargi، CORS مفتوح للجميع. الـ JWT يُحَوَّل في وقت التشغيل لكل زائر، فلا توجد أسرار في الـ HTML.

بدء سريع (3 خطوات)

افتح widget.amargicreative.com وانقر "New publication". اختر المصدر (وكيل Agents، أو قناة Reach Webchat، أو نموذج/قاعدة معرفة Escalate).
اختر ثيمة الواجهة (Classic — فقاعة كلام، Modern — لوحة مستديرة، Minimal — شريط نحيل). معاينة مباشرة في المحرّر.
انسخ مقتطف الـ <script> من علامة تبويب "Snippet" والصقه قبل </body> على موقعك. ستظهر الفقاعة في أقل من خمس دقائق.

المقتطف

<script
  src="https://agents-api.amargicreative.com/sdk/v2/amargi-widget.umd.js"
  data-key="wid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  defer
></script>

بدّل v2 بـ v1 أو v3 لتغيير الثيمة (Classic / Minimal). المفتاح data-key فريد لكل نشر — انسخه من علامة تبويب "Snippet" في المحرّر.

مفاهيم رئيسيّة

النشر (Publication)

وحدة الإعداد الأساسيّة. تربط مصدراً واحداً + ثيمة واحدة + مفتاحاً عاماً واحداً + قائمة نطاقات مسموحة + علم نشط/مُعطَّل. غيّر الثيمة أو قائمة النطاقات أو حالة النشاط دون لمس الكود في موقعك. كل نشر له صفحة محرّر مع علامات تبويب: General، Snippet، Origins، Analytics.

المصدر (Source)

Agents — يفعّل وضع الذكاء الاصطناعي. الويدجت يتحدّث إلى وكيل Agents مع كل قواعد سلامة الذكاء الاصطناعي العاديّة (RAG، استدعاءات الأدوات، التسليم البشري).
Reach — يفعّل وضع الدردشة الحيّة. يتصل بقناة Reach Webchat، الزائر يدردش مع وكيل بشريّ في صندوق وارد Reach.
Escalate — يفعّل وضعَي النموذج وبحث قاعدة المعرفة. النموذج يُنشئ تذكرة عند الإرسال؛ بحث قاعدة المعرفة يعرض المقالات قبل أن يكتب الزائر.

الثيمة (UI Theme)

Classic (v1) — فقاعة كلام كلاسيكيّة، ودودة، حدود مستديرة معتدلة.
Modern (v2) — لوحة مستديرة، حدود ناعمة جداً، أمامية للعلامة. الافتراضيّة للنشرات الجديدة.
Minimal (v3) — شريط نحيل بنص "Chat with us" بجانب الأيقونة. فاخر، يبدو غير-Amargi.

قائمة النطاقات المسموحة (Allowed origins)

قائمة بأصول HTTPS مسموح لها بتحميل النشر. قائمة فارغة = أي أصل (الافتراضي). أي إدخال غير فارغ يُنفذ قائمة بيضاء صارمة — يدعم نطاقات كاملة (https://example.com)، أنماط بدائل (*.example.com)، أو أسماء مضيف فقط (example.com). الأصول خارج القائمة تحصل على 204 صامتة بدلاً من بيانات الإعداد.

تحليلات القمع (Funnel analytics)

كل نشر يلتقط ثلاثة عدّادات حياة كاملة: loads_total, opens_total, messages_total. الأوّل يزيد عند كل جلب لإعدادات الويدجت (تحميل صفحة فيها الـ <script>)؛ الثاني عند نقر الفقاعة؛ الثالث عند إرسال أوّل رسالة. معدّلات التحويل بين كل مرحلة تظهر في علامة تبويب "Analytics" في المحرّر.

مهامّ شائعة

تغيير الثيمة بعد النشر

افتح المحرّر، علامة تبويب General.
بدّل قيمة "UI theme" — يحفظ المحرّر تلقائياً.
علامة تبويب Snippet ستُظهر مسار الـ SDK الجديد (v1 / v2 / v3). انسخه إلى موقعك مرة واحدة.

تقييد النشر بنطاقات معيّنة

علامة تبويب Origins، أضف كل نطاق على سطر منفصل.
استخدم *.example.com لتطابق كل النطاقات الفرعيّة.
الأصول الجديدة تأخذ تأثيراً فوراً — لا حاجة لإعادة نشر.

إيقاف نشر مؤقتاً

علامة تبويب General، غيّر الحالة إلى "Paused".
النشر المتوقّف يعيد 404 على الـ resolver. الويدجت يفشل بصمت على موقعك (لا فقاعة)، لا رسالة خطأ مرئيّة للزائر.
استأنف بـ "Active" متى شئت.

حذف نشر

الحذف ناعم — يحدّد العمود deleted_at في القاعدة، فيتوقّف الـ resolver عن خدمة الإعداد، لكن الصفّ يبقى للتدقيق. لاستعادة، اتّصل بالدعم.

مرجع التضمين

مسارات SDK المتاحة:

https://agents-api.amargicreative.com/sdk/v1/amargi-widget.umd.js — ثيمة Classic.
https://agents-api.amargicreative.com/sdk/v2/amargi-widget.umd.js — ثيمة Modern (افتراضي).
https://agents-api.amargicreative.com/sdk/v3/amargi-widget.umd.js — ثيمة Minimal.

سمات <script> المدعومة:

data-key — مطلوب. مفتاح النشر العام (wid_…).
data-client-id, data-branch-id, data-user-id — اختيارية. تمرّ إلى init الـ JWT لتمكين تحديد نطاق المستأجر الفرعي (RAG، الفوترة، السجلّ).
defer — موصى به. يحمّل الحزمة بعد تحليل HTML.

التكامل مع المنتجات الأخرى

Agents — وضع AI يستدعي وكيل Agents مع كل قواعد سلامة الذكاء الاصطناعي العاديّة. إذا أصدر الوكيل إشارة human_handoff، فالويدجت يتحوّل إلى Live (إذا كان ممكّناً) ويُسلّم النصّ.
Reach — الوضع الحيّ يتصل بقناة Reach Webchat. المحادثة تصل إلى صندوق Reach الوارد كأيّ محادثة أخرى — التعيينات، الملاحظات الداخليّة، الردود.
Escalate — وضع النموذج ينشئ تذكرة Escalate عند الإرسال. وضع البحث في قاعدة المعرفة يعرض المقالات المنشورة. إشارة create_ticket من وكيل Agents تحوّل الويدجت إلى Form (إذا كان ممكّناً) مع نصّ المحادثة معبأ في الحقل الأوّل.

الحصول على المساعدة

دعم البريد الإلكترونيّ: contact@amargicreative.com
الصفحة التسويقيّة: /products/widget.