تثبيت الأداة

Shayan Taslimتم التحديث

يتطلب تثبيت الأداة مقتطفًا واحدًا. الصقه قرب نهاية صفحة HTML، قبل وسم الإغلاق </body> مباشرةً:

HTML
<script>
  window.uj ||= new Proxy(
    {},
    {
      get: (_, p) =>
        p == 'then'
          ? 0
          : (...a) => {
              (window.$ujq ||= []).push([p, ...a]);
            }
    }
  );
  uj.init('YOUR_PROJECT_ID');
</script>
<script type="module" async src="https://cdn.userjot.com/sdk/v3/uj.js"></script>

اعثر على YOUR_PROJECT_ID ضمن Settings → Login في Secrets (أو انسخ المقتطف المعبأ مسبقًا من صفحة Share في لوحة التحكم). بعد تحميله، يظهر زر التشغيل في الركن السفلي الأيمن من صفحتك.

ينشئ المقتطف المضمّن وكيلاً window.uj يضع الاستدعاءات التي لا تنتظر نتيجة (init، open، close، toggle، identify، logout، setTheme، setLocale، destroy) في قائمة انتظار حتى يكتمل تحميل SDK، ثم يعيد تشغيلها.

ترتيب الاستدعاءات لا يهم

يمكنك وضع init وidentify وopen في قائمة الانتظار خلال دورة التنفيذ نفسها، قبل اكتمال تحميل SDK:

HTML
<script>
  window.uj ||= new Proxy(
    {},
    {
      get: (_, p) =>
        p == 'then'
          ? 0
          : (...a) => {
              (window.$ujq ||= []).push([p, ...a]);
            }
    }
  );
  uj.init('YOUR_PROJECT_ID');
  uj.identify({ user: { id: 'user-123', email: 'user@example.com' } });
</script>
<script type="module" async src="https://cdn.userjot.com/sdk/v3/uj.js"></script>
Note

يعيد الوكيل الذي يسبق التحميل undefined لكل استدعاء. إذا كنت تحتاج إلى قيم مُعادة أو وعود (Promises)، مثل await uj.identify(...) أو uj.createEmbed(...) أو uj.on(...) أو uj.getState()، فانتظر تحميل نص SDK قبل استدعائها.

من دون برامج نصية مضمنة (سياسة CSP صارمة)

إذا كان موقعك يحظر النصوص البرمجية المضمّنة، فاستخدم التثبيت بوسم واحد مع data-project لتهيئة SDK ذاتيًا:

HTML
<script
  type="module"
  async
  src="https://cdn.userjot.com/sdk/v3/uj.js"
  data-project="YOUR_PROJECT_ID"
></script>

لا يزال بإمكانك استدعاء طرق window.uj من الحزمة البرمجية الخاصة بك بعد تحميل النص البرمجي. وإذا كان الرمز لديك يستدعي أيضًا uj.init(...)، فسيكون لاستدعائك الصريح الأولوية على data-project.

توجيهات سياسة أمان المحتوى (CSP)

إذا كان تطبيقك يفرض سياسة أمان المحتوى، فاسمح بنطاقات UserJot التالية:

  • script-src: https://cdn.userjot.com

  • connect-src: https://widget.userjot.com wss://widget.userjot.com https://collect.jotlens.com (يرسل SDK إشارات قياس عن بُعد خفيفة الوزن خاصة بالويدجت إلى collect.jotlens.com على المضيفات غير المحلية)

  • img-src: https://media.userjot.com (وhttps://cdn.userjot.com للأصول المرفوعة)

  • style-src وfont-src: https://cdn.userjot.com (تُستضاف الخطوط ذاتيًا؛ ولا حاجة إلى السماح بخطوط Google Fonts)

  • frame-src: https://<your-workspace>.userjot.com (أو نطاقك المخصص) إذا كنت تستخدم التضمينات المضمّنة

React وNext.js وتطبيقات الصفحة الواحدة

  • حمّل https://cdn.userjot.com/sdk/v3/uj.js مرة واحدة في التخطيط الجذر (على سبيل المثال، باستخدام <Script strategy="afterInteractive" /> في Next.js أو ضمن index.html). لا تحقن وسوم نصوص برمجية مكررة عند تغيير المسارات.

  • استدعِ uj.init('YOUR_PROJECT_ID', ...) مرة واحدة عند بدء تشغيل التطبيق، واستدعِ uj.identify(...) / uj.logout() عند تغير حالة المصادقة.

  • نظّف أي اشتراكات uj.on(...) ومقابض embed.destroy() في دالة تنظيف المكوّن (useEffect return).

الإعدادات

مرّر الخيارات كوسيطة ثانية إلى init:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    position: 'right', // 'left' or 'right'
    theme: 'auto', // 'auto', 'light', or 'dark'
    launcher: true // false hides the default button
  },
  locale: 'en-US' // optional override
});

جميع الخيارات اختيارية. عيّن launcher: false لفتح الأداة من زر خاص بك بدلًا من زر التشغيل الافتراضي. راجع التحكم في الأداة للاطلاع على أمثلة.

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

بعد تحميل صفحتك:

  1. يظهر زر التشغيل في الزاوية التي ضبطتها.

  2. يؤدي النقر عليه إلى فتح الأداة المصغّرة.

  3. يمكنك تصفح الرئيسية والملاحظات (بما في ذلك خارطة الطريق عند تفعيلها) داخل الويدجت، بالإضافة إلى التحديثات عند تفعيل سجل التغييرات العام.

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

المشكلات الشائعة

الأداة المصغّرة لا تظهر

  • تأكد من وجود كلا وسمي النص البرمجي (أو الوسم الواحد مع data-project).

  • تحقق من أن YOUR_PROJECT_ID يطابق القيمة في Settings → Login → Secrets.

  • تحقق من أنك لم تمرر widget: false أو launcher: false إلى init.

  • تحقق من وحدة تحكم المتصفح بحثًا عن أخطاء سياسة أمان المحتوى التي تحظر cdn.userjot.com أو widget.userjot.com.

يبدو أن الاستدعاءات لا تفعل شيئًا

إذا لم يفعل uj.open() أو uj.identify(...) شيئًا، فتأكد من تشغيل uj.init(...) على الصفحة. تنتظر الاستدعاءات المدرجة في قائمة الانتظار قبل init إلى أن يتم تشغيل init، ويسجل SDK تحذيرًا في وحدة التحكم إذا ظلت استدعاءات في قائمة الانتظار من دون init.

الخطوة التالية

اربط الأداة بالمستخدمين الذين سجّلوا الدخول من خلال التعرّف على المستخدمين.

هل أجاب هذا عن سؤالك؟