إنتقل إلى المحتوى الرئيسي

أداة الموقع

لكل وكيل أداة دردشة واحدة للموقع: الدردشة التي يفتحها الزوار على موقعك ويجيب عنها ذكاء الوكيل الاصطناعي. يُعيدها GET /v1/agents/{agentId}/widget مع الكود الذي تلصقه في الصفحة، فيستطيع منشئ مواقع أو إضافة لنظام إدارة محتوى أو سكربت نشر تثبيت الدردشة دون أن ينسخ أحد الكود من لوحة التحكم. ويُخبرك أيضاً هل الأداة مفعّلة وكيف تبدو. راجع أداة الموقع لترى كيف تعمل في لوحة التحكم.

كيف أحصل على كود التضمين؟​

curl https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/widget \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

يحمل embed_code نسختين من الكود: default وheadless. الصق إحداهما مرة واحدة في كل صفحة، قبل وسم body الختامي مباشرة، كما عادت تماماً. اجلبها من الواجهة البرمجية بدل كتابة كودك الخاص: فقد تتغيّر، والواجهة تُعيد النسخة الحالية دائماً. وكل الحقول في مرجع جلب أداة الموقع لوكيل.

أي كود تضمين أستخدم؟​

  • default يضيف زر الدردشة العائم من مجيب، مع رسالة الأداة الافتتاحية في فقاعة بجانبه. هو ودجت جاهز في لوحة التحكم، والخيار المناسب لأغلب المواقع.
  • headless لا يضيف زراً: تفتح صفحتك الدردشة من زرها أو رابطها الخاص. هو تكامل مخصص في لوحة التحكم. ولا تظهر معه الرسالة الافتتاحية.

كيف أفتح الدردشة من زري الخاص؟​

الصق كود headless، ثم افتح الدردشة عبر MojeebWidget. لا تُنشئ الأداة window.MojeebWidget إلا بعد تحميل إعداداتها، بعد الصفحة نفسها بلحظة، لذا انتظرها قبل أن تستخدمها:

<button id="chat-button" type="button">Chat with us</button>

<!-- Paste the headless embed code from the API here -->

<script>
  var waitForMojeeb = setInterval(function () {
    if (window.MojeebWidget) {
      clearInterval(waitForMojeeb);
      MojeebWidget.attach('#chat-button');
    }
  }, 100);
</script>

يجعل MojeebWidget.attach(selector) كل عنصر يطابق محدِّد CSS يفتح الدردشة عند النقر عليه. ويمكنك أيضاً استدعاء MojeebWidget.open() بنفسك، أو MojeebWidget.open({ message: "Need help with your order?" }) لتفتح الدردشة بسطر افتتاحي من الوكيل تكتبه أنت. أما MojeebWidget.close() وMojeebWidget.toggle() وMojeebWidget.isOpen() فتفعل ما تدل عليه أسماؤها. وكودا التضمين كلاهما يُنشئان MojeebWidget نفسه، لذا تستطيع أيضاً فتح الأداة الافتراضية من روابطك الخاصة.

هل تغيّر قراءة الأداة شيئاً؟​

في المرة الأولى فقط. الوكيل الذي ليست لديه أداة بعد تُنشأ له واحدة عند أول قراءة، بإعدادات لوحة التحكم الافتراضية ومفعّلة، فيُعيد أول استدعاء دائماً كوداً يمكنك لصقه. بعد ذلك لا تغيّر القراءة شيئاً. وهي الأداة نفسها التي تعرضها لوحة التحكم، ومعرّفها لا يتغيّر أبداً، فيبقى الكود الذي لصقته يعمل.

أسئلة شائعة​

هل معرّف الأداة سرّي؟​

لا. هو data-widget-id في كود التضمين، فهو في مصدر صفحة كل موقع توجد فيه الأداة، ولا يتيح إلا للزوار الدردشة مع الوكيل. السرّ هو مفتاح API: لا تضعه في صفحة ويب أبداً.

هل أستطيع عرض الدردشة في تطبيق جوال؟​

نعم، ودون كود التضمين. يحمّل التطبيق صفحة الدردشة في WebView بقيمة id للأداة، ولا يحتاج إلى مفتاح API. راجع إضافة الدردشة إلى تطبيق الجوال لتجد العنوان، والرسائل التي تتبادلها الدردشة مع التطبيق، ومكوّن React Native.

هل أستطيع تغيير لون الأداة أو رسالتها الافتتاحية عبر الواجهة البرمجية؟​

ليس بعد. غيّرهما من لوحة التحكم. يبقى كود التضمين كما هو، فتُظهر الصفحات التي تحتويه التغيير في المرة التالية التي تُحمَّل فيها.

هل يمكن أن يكون للوكيل أكثر من أداة؟​

لا. لكل وكيل أداة واحدة. ولوضع الدردشة نفسها على عدة مواقع، الصق كود التضمين نفسه في كل منها.

لماذا MojeebWidget غير معرّف؟​

لم تنتهِ الأداة من تحميل إعداداتها بعد. تحقّق من وجود window.MojeebWidget كل 100 ملّي ثانية تقريباً، ولا تستدعه إلا بعد أن يوجد: فمستمع DOMContentLoaded يعمل عادةً قبل الأوان. والصق كود التضمين مرة واحدة فقط في كل صفحة: فالنسخة الثانية تُشغّل أداة ثانية بزر دردشة خاص بها، وتحلّ محل window.MojeebWidget.

ماذا تعني enabled: false؟​

الأداة متوقفة: لا يستطيع الزوار بدء دردشة أو إرسال رسائل، حتى في الدردشات المفتوحة، وتُظهر الدردشة أنها غير متاحة. ولا يوجد في لوحة التحكم مفتاح لذلك اليوم، فإن كانت أداتك تُظهر false فتواصل مع دعم مجيب.

يُرسل موقعي سياسة أمان المحتوى (Content-Security-Policy). ماذا أسمح؟​

يأتي سكربت الأداة من chat.mojeeb.app، ونافذة الدردشة من شبكة توزيع المحتوى (CDN) الخاصة بمجيب، وإعداداتها من واجهة مجيب البرمجية، وخطها من Google Fonts، وتضيف عنصر أنماط (style) إلى صفحتك. اسمح بما يلي:

  • script-src: https://chat.mojeeb.app. وكود التضمين الأقدم يحمّل السكربت من https://mojeebcdn.z7.web.core.windows.net بدلاً منه: اسمح بالعنوان الموجود في src في كودك.
  • frame-src: https://mojeebcdn.z7.web.core.windows.net
  • connect-src: https://mojeebapi.azurewebsites.net
  • style-src: 'unsafe-inline' وhttps://fonts.googleapis.com
  • font-src: https://fonts.gstatic.com

وإن لم تظهر الدردشة بعد ذلك، فافتح وحدة التحكم في متصفحك: الطلب المحظور يذكر العنوان الذي يجب السماح به، والنمط المرفوض يذكر توجيه style-src.

هل أستطيع الحصول على رابط التثبيت من لوحة التحكم عبر الواجهة البرمجية؟​

لا. تستطيع لوحة التحكم مشاركة رابط لتعليمات التثبيت مع مطوّر موقعك. أما عبر الواجهة البرمجية فأرسل له كود التضمين بدلاً منه.

ما النطاق الذي يحتاجه؟​

connections:read، لأن الأداة إحدى قنوات الوكيل. ويحمله كل مفتاح اليوم؛ راجع التوثيق.