تثبيت الأداة
يتطلب تثبيت الأداة مقتطفًا واحدًا. الصقه قرب نهاية صفحة HTML، قبل وسم الإغلاق </body> مباشرةً:
<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:
<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>يعيد الوكيل الذي يسبق التحميل undefined لكل استدعاء. إذا كنت تحتاج إلى قيم مُعادة أو وعود (Promises)، مثل await uj.identify(...) أو uj.createEmbed(...) أو uj.on(...) أو uj.getState()، فانتظر تحميل نص SDK قبل استدعائها.
من دون برامج نصية مضمنة (سياسة CSP صارمة)
إذا كان موقعك يحظر النصوص البرمجية المضمّنة، فاستخدم التثبيت بوسم واحد مع data-project لتهيئة SDK ذاتيًا:
<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.comconnect-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()في دالة تنظيف المكوّن (useEffectreturn).
الإعدادات
مرّر الخيارات كوسيطة ثانية إلى init:
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 لفتح الأداة من زر خاص بك بدلًا من زر التشغيل الافتراضي. راجع التحكم في الأداة للاطلاع على أمثلة.
تحقّق من التثبيت
بعد تحميل صفحتك:
يظهر زر التشغيل في الزاوية التي ضبطتها.
يؤدي النقر عليه إلى فتح الأداة المصغّرة.
يمكنك تصفح الرئيسية والملاحظات (بما في ذلك خارطة الطريق عند تفعيلها) داخل الويدجت، بالإضافة إلى التحديثات عند تفعيل سجل التغييرات العام.
إذا كان مركز المساعدة منشورًا أو كانت المحادثات مفعّلة، فستظهر علامتا التبويب المساعدة والرسائل تلقائيًا، دون الحاجة إلى إجراء تغييرات إضافية على النص البرمجي.
المشكلات الشائعة
الأداة المصغّرة لا تظهر
تأكد من وجود كلا وسمي النص البرمجي (أو الوسم الواحد مع
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.
الخطوة التالية
اربط الأداة بالمستخدمين الذين سجّلوا الدخول من خلال التعرّف على المستخدمين.