مرجع SDK
تتوفر SDK عبر window.uj. تُضاف الاستدعاءات التي لا تنتظر نتيجة، والمُجراة عبر الوكيل المضمّن لما قبل التحميل (init، open، close، toggle، identify، logout، setLocale، setTheme، destroy) إلى قائمة انتظار، ثم تُعاد بعد تحميل uj.js. أما الاستدعاءات التي تُرجع قيمًا أو وعودًا (await uj.identify(...)، uj.createEmbed(...)، uj.on(...)، uj.getState()، uj.version)، فيجب أن يكون نص SDK البرمجي قد حُمّل أولًا.
uj.version
سلسلة إصدار SDK، مثل 1.0.0.
uj.init(projectId, options?)
تهيّئ SDK. وتُرجع وعدًا يُحلّ مع حالة SDK بعد اكتمال التحميل.
const state = await uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: true, // boolean or { selector: string }
whispers: true, // default whisper behavior
notifications: { updates: 'whisper' }, // 'whisper', 'full', or 'none'
position: 'right', // 'left' or 'right'
offset: { bottom: 20 }, // corner distance in pixels: { bottom, side }
theme: 'auto' // 'auto', 'light', or 'dark'
},
locale: 'es-MX', // optional language override
pageContext: 'origin', // 'origin', 'path', or 'none'
onReady: () => {},
onError: (error) => {}
});الخيار | القيمة الافتراضية | الوصف |
|---|---|---|
|
| يعرض |
|
| يخفي |
|
| إشعارات مؤقتة تظهر عند زاوية الأداة. وهي مستقلة عن زر التشغيل: تظل تظهر عند إخفاء الزر ما لم تُضبط على |
|
| يعرض |
|
| جانب الشاشة الذي تفتح فيه الأداة. |
|
| المسافة بالبكسل بين المشغّل والتلميحات وحواف إطار العرض. |
|
| اتّباع إعداد النظام أو فرض الوضع الفاتح أو الداكن. |
| المتصفح ← الإعداد الافتراضي لمساحة العمل | تجاوز اللغة. عند عدم تحديدها، تُطابق لغة متصفح الزائر مع اللغات المفعّلة في مساحة العمل، ثم تُستخدم اللغة الافتراضية لمساحة العمل عند عدم وجود تطابق. يدعم ذلك لغات UserJot الأربع عشرة كلها؛ وتُحوَّل العلامات الإقليمية مثل |
|
| مقدار عنوان URL للصفحة الحالية الذي تتم مشاركته مع فريقك في المحادثات والزوار المباشرين. يرسل |
| يُستدعى عند جاهزية SDK. | |
| يُستدعى عند حدوث أي خطأ في SDK. |
لا تُرفض الوعود المُعادة عند حدوث مشكلات في الشبكة (تحقق من state.status === 'ready'). وهي تُرفض فقط عند حدوث أخطاء برمجية، مثل معرّف مشروع فارغ أو خيارات غير سليمة (INVALID_OPTIONS، recoverable: false).
يعمل وضع التحديث الكامل دون مشغّل أو تلميحات أو اشتراكات المضيف. راجع إعلانات التحديثات للاطّلاع على قواعد الظهور والتركيز وتخزين حالة المشاهدة بالتفصيل.
uj.ready()
يُرجع الوعد نفسه الذي يُرجعه init. يفيد ذلك عندما يكون الرمز الذي يحتاج إلى SDK منفصلًا عن رمز التهيئة.
const state = await uj.ready();uj.identify(input)
يحدّد المستخدم الحالي. ويُرجع وعدًا بالنتيجة. راجع تحديد هوية المستخدمين والهوية الموقّعة.
const result = await uj.identify({
token: 'OPTIONAL_JWT_FROM_YOUR_SERVER',
user: {
id: 'user-123', // required if no token is given
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
avatar: 'https://example.com/avatar.jpg',
traits: { plan: 'pro' }
},
companies: [
{
id: 'acme',
name: 'ACME Inc.',
domain: 'acme.com',
logo: 'https://acme.com/logo.png',
traits: { plan: 'enterprise' }
}
]
});
result.viewer; // the identified user, or null
result.identityTrust; // 'signed', 'unsigned', or null
result.warnings; // [{ code, message, field? }]لهذا viewer البنية التالية:
{
id: 'mem_...', // UserJot's member ID, not the user.id you sent
firstName: 'Ada', // string or null
lastName: 'Lovelace', // string or null
avatar: { url: 'https://...', blurhash: '...' } // or null; blurhash optional
}التحذيرات ومفاتيح السمات المحجوزة
الرمز |
| المعنى |
|---|---|---|
| مفتاح السمة | المفتاح محجوز لـ UserJot، ولذلك تم تجاهله. |
| الشركة | تتطلب مساحة العمل عضوية شركة موقّعة، ولم تكن هذه الشركة واردة في الرمز. |
|
| المستخدم مشرف مساحة عمل أو مالكها. تُطبَّق سماته وشركاته؛ أما اسمه وصورته الرمزية وبريده الإلكتروني فتُدار من لوحة التحكم. |
مفاتيح السمات التالية محجوزة ويتم تجاهلها (مع إصدار RESERVED_TRAIT_KEY_IGNORED): id، externalId، external_id، email، name، firstName، first_name، lastName، last_name، avatar، avatarUrl، avatar_url، role، type، companies، company، companyId، company_id، createdAt، created_at، updatedAt، updated_at، deletedAt، deleted_at، و__proto__.
يلزم توفير token أو user.id على الأقل. إن استدعاء identify مرة أخرى بالمدخلات نفسها لا يفعل شيئًا ما دامت الجلسة نشطة؛ وبعد انتهاء صلاحيتها، ترسل المدخلات نفسها طلبًا جديدًا. أما استدعاؤه بمدخلات جديدة فيبدّل الجلسة. إذا تداخلت عدة استدعاءات، يُعتمد آخرها. identify هي الطريقة الوحيدة التي ترفض عند حدوث إخفاقات وقت التشغيل (IDENTIFY_FAILED)، وتفرض فترة انتظار محلية بعد استجابات HTTP 429 (مع مراعاة Retry-After، وتُحصر المدة بين ثانية واحدة وساعة واحدة، وتكون 60 ثانية افتراضيًا).
uj.logout()
يمسح الهوية الحالية ويعيد الجلسة إلى حالة مجهول.
await uj.logout();uj.open(target?)
يفتح الأداة المصغّرة. إذا لم تُمرَّر أي وسيطة، تُفتح من حيث توقّف المستخدم. يُحلّ الوعد عند ظهور الأداة المصغّرة.
await uj.open();
await uj.open({ to: 'home' });
await uj.open({ to: 'feedback' });
await uj.open({ to: 'feedback', compose: true });
await uj.open({ to: 'feedback', submissionId: 'POST_ID' });
await uj.open({ to: 'roadmap' });
await uj.open({ to: 'updates' });
await uj.open({ to: 'updates', updateId: 'UPDATE_ID' });
await uj.open({ to: 'messages' });
await uj.open({ to: 'messages', compose: { text: 'Prefilled message' } });
await uj.open({ to: 'notifications' });
await uj.open({ to: 'help' });
await uj.open({ to: 'help', article: 'ARTICLE_SLUG' });
await uj.open({ to: 'help', collection: 'COLLECTION_SLUG' });
await uj.open({ to: 'help', query: 'Search text' });يقبل هدف help واحدًا على الأكثر من article أو collection أو query. يأخذ كل من article وcollection اسم المعرّف في عنوان URL، وتُعيد المعرّفات القديمة التوجيه إلى الصفحة المنقولة. يُرفض الوعد مع INVALID_NAVIGATION للأهداف غير المعروفة أو التركيبات غير الصالحة.
uj.close()
يخفي الأداة. يُنفّذ بشكل متزامن وآمن في أي وقت.
uj.toggle()
يفتح الأداة المصغّرة إذا كانت مغلقة، ويغلقها إذا كانت مفتوحة.
uj.createEmbed(options?)
يعرض صفحة UserJot داخل حاوية في صفحتك. ويعيد وحدة تحكّم. راجع تضمين الصفحات ضمن الصفحة.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
يغيّر لغة الأداة أثناء التشغيل:
await uj.setLocale('pt-BR');uj.setTheme(theme)
يغيّر مظهر الأداة بشكل متزامن ('auto' أو 'light' أو 'dark'). تؤدي القيم غير الصالحة إلى إصدار INVALID_OPTIONS عبر الحدث error. بما أن init يطبّق مظهره الخاص دائمًا (ويستخدم 'auto' افتراضيًا)، فمرّر المظهر الأولي في init بدلًا من استدعاء setTheme قبل init.
uj.getState()
يُرجع لقطة للقراءة فقط لحالة SDK:
{
status: 'ready', // 'idle' | 'initializing' | 'ready' | 'error' | 'destroyed'
projectId: 'proj_...',
locale: 'en-US',
unreadCount: 3, // number, or null before the first fetch
presence: 'online', // 'online' | 'neutral'
lastError: null,
widget: {
enabled: true,
open: false,
position: 'right',
theme: 'auto'
},
session: {
status: 'identified', // 'anonymous' | 'identifying' | 'identified'
identityTrust: 'signed',
viewer: { id: 'mem_...', firstName: 'Ada', lastName: 'Lovelace', avatar: null }
}
}uj.on(event, listener)
يشترك في حدث ويُرجع دالة لإلغاء الاشتراك. وتظل أدوات الاستماع فعّالة بعد destroy().
الحدث | البيانات | موعد الإطلاق |
|---|---|---|
| state | اكتمل التحميل. يعيد التشغيل فورًا إذا كان قد اكتمل بالفعل. |
| state | عند حدوث أي تغيير في الحالة. |
| state | عندما تصبح الأداة المصغّرة مرئية. |
| state | عندما تُخفى الأداة المصغّرة. |
|
| عند تغيير الهوية، بما في ذلك تسجيل الخروج. |
|
| تغيّر عدد العناصر غير المقروءة. يعيد التشغيل فورًا إذا كانت الأداة جاهزة وتم جلب البيانات بالفعل. |
|
| تغيّرت إتاحة الفريق بين |
| error | عند حدوث أي خطأ في SDK. |
| state | عند إتلاف SDK. |
يؤدي الاشتراك في unread أو presence إلى إبقاء القيمتين محدّثتين في الخلفية، حتى عندما يكون المشغّل الافتراضي مخفيًا.
uj.destroy(options?)
يزيل الأداة وكل التضمينات والجلسة من الصفحة:
uj.destroy();
uj.destroy({ clearConversationData: true });يمسح clearConversationData أيضًا أذونات المحادثات المحلية المجهولة والمسودات وبيانات الاتصال المحفوظة (وهو مفيد على الأجهزة المشتركة).
سمات DOM لالتقاط لقطات الشاشة
عندما يلتقط المستخدم لقطة شاشة داخل الصفحة من أداة إنشاء الملاحظات في الودجت (باستخدام طريقة الالتقاط الاحتياطية لـ DOM)، يخفي UserJot تلقائيًا واجهات الودجت ويحجب input[type="password"] وinput[type="email"] وinput[type="tel"] وinput[name*="token" i] وinput[name*="secret" i]. ويمكنك أيضًا التحكم في الالتقاط لعناصر معينة باستخدام سمات HTML:
السمة | التأثير أثناء التقاط لقطة شاشة داخل الصفحة |
|---|---|
| يستبعد العنصر تمامًا من لقطة الشاشة الملتقطة. |
| يحجب المحتوى المرئي للعنصر في لقطة الشاشة الملتقطة. |
| يحجب حقول |
الأخطاء
تكون الأخطاء بالصيغة { code, message, recoverable, cause? }.
الرمز | المعنى |
|---|---|
| تم استدعاء |
| تلقت |
| تلقّى |
| يفتقد إدخال |
| رفض الخادم استدعاء identify (مثلًا بسبب رمز غير صالح، أو توقيع مفقود في الوضع الصارم، أو تعارض |
| تعذّر تحميل SDK. تحقق من معرّف المشروع وقواعد CSP والاتصال بالشبكة. |
| تم تنفيذ استدعاء بينما كان SDK في حالة فشل. |
| تم استدعاء |
| المراسلة معطّلة لمساحة العمل هذه. تفتح الأداة الصفحة الرئيسية بدلًا من ذلك. |
| مركز المساعدة غير منشور لمساحة العمل هذه. تفتح الأداة الصفحة الرئيسية بدلًا من ذلك. |
| عنصر |
| تعذّر تحميل واجهة الأداة. |
| حاوية التضمين غير موجودة. |
| تم تنفيذ استدعاء بعد |
| أي شيء آخر. |