مرجع SDK

Shayan Taslimتم التحديث

تتوفر 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 بعد اكتمال التحميل.

JavaScript
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) => {}
});

الخيار

القيمة الافتراضية

الوصف

widget

true

يعرض true الأداة بالإعدادات الافتراضية. ويعطّلها false. أما الكائن فيضبط إعداداتها.

widget.launcher

true

يخفي false الزر الافتراضي. ويربط { selector } الأداة بعنص من اختيارك.

widget.whispers

true

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

widget.notifications.updates

'whisper'، أو 'none' عندما يكون whispers: false

يعرض 'whisper' التحديثات في إشعار منبثق؛ ويفتح 'full' أحدث إدخال لم تتم مشاهدته في قارئ عناصر واجهة المستخدم؛ أما 'none' فيمنع الإعلان عن التحديثات مع الإبقاء عليها كغير مقروءة. تتجاوز القيم المحددة صراحةً whispers للتحديثات فقط.

widget.position

'right'

جانب الشاشة الذي تفتح فيه الأداة.

widget.offset

{ bottom: 20, side: 20 }

المسافة بالبكسل بين المشغّل والتلميحات وحواف إطار العرض.

widget.theme

'auto'

اتّباع إعداد النظام أو فرض الوضع الفاتح أو الداكن.

locale

المتصفح ← الإعداد الافتراضي لمساحة العمل

تجاوز اللغة. عند عدم تحديدها، تُطابق لغة متصفح الزائر مع اللغات المفعّلة في مساحة العمل، ثم تُستخدم اللغة الافتراضية لمساحة العمل عند عدم وجود تطابق. يدعم ذلك لغات UserJot الأربع عشرة كلها؛ وتُحوَّل العلامات الإقليمية مثل es-MX إلى اللغة المقابلة لها.

pageContext

'origin'

مقدار عنوان URL للصفحة الحالية الذي تتم مشاركته مع فريقك في المحادثات والزوار المباشرين. يرسل 'origin' اسم المضيف فقط، ويتضمن 'path' المسار (مع حذف سلاسل الاستعلام و#fragments)، ولا يرسل 'none' أي شيء.

onReady

يُستدعى عند جاهزية SDK.

onError

يُستدعى عند حدوث أي خطأ في SDK.

لا تُرفض الوعود المُعادة عند حدوث مشكلات في الشبكة (تحقق من state.status === 'ready'). وهي تُرفض فقط عند حدوث أخطاء برمجية، مثل معرّف مشروع فارغ أو خيارات غير سليمة (INVALID_OPTIONS، recoverable: false).

يعمل وضع التحديث الكامل دون مشغّل أو تلميحات أو اشتراكات المضيف. راجع إعلانات التحديثات للاطّلاع على قواعد الظهور والتركيز وتخزين حالة المشاهدة بالتفصيل.

uj.ready()

يُرجع الوعد نفسه الذي يُرجعه init. يفيد ذلك عندما يكون الرمز الذي يحتاج إلى SDK منفصلًا عن رمز التهيئة.

JavaScript
const state = await uj.ready();

uj.identify(input)

يحدّد المستخدم الحالي. ويُرجع وعدًا بالنتيجة. راجع تحديد هوية المستخدمين والهوية الموقّعة.

JavaScript
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 البنية التالية:

JavaScript
{
  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
}

التحذيرات ومفاتيح السمات المحجوزة

الرمز

field

المعنى

RESERVED_TRAIT_KEY_IGNORED

مفتاح السمة

المفتاح محجوز لـ UserJot، ولذلك تم تجاهله.

UNSIGNED_COMPANY_IGNORED

الشركة id

تتطلب مساحة العمل عضوية شركة موقّعة، ولم تكن هذه الشركة واردة في الرمز.

PRIVILEGED_PROFILE_IGNORED

firstName أو lastName أو avatar أو email

المستخدم مشرف مساحة عمل أو مالكها. تُطبَّق سماته وشركاته؛ أما اسمه وصورته الرمزية وبريده الإلكتروني فتُدار من لوحة التحكم.

مفاتيح السمات التالية محجوزة ويتم تجاهلها (مع إصدار 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()

يمسح الهوية الحالية ويعيد الجلسة إلى حالة مجهول.

JavaScript
await uj.logout();

uj.open(target?)

يفتح الأداة المصغّرة. إذا لم تُمرَّر أي وسيطة، تُفتح من حيث توقّف المستخدم. يُحلّ الوعد عند ظهور الأداة المصغّرة.

JavaScript
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 داخل حاوية في صفحتك. ويعيد وحدة تحكّم. راجع تضمين الصفحات ضمن الصفحة.

JavaScript
const embed = uj.createEmbed({
  container: '[data-userjot-embed]',
  path: '/',
  basePath: '/feedback',
  theme: 'auto',
  onReady: () => {},
  onError: (error) => {}
});

embed.navigate('/roadmap');
embed.destroy();

uj.setLocale(locale)

يغيّر لغة الأداة أثناء التشغيل:

JavaScript
await uj.setLocale('pt-BR');

uj.setTheme(theme)

يغيّر مظهر الأداة بشكل متزامن ('auto' أو 'light' أو 'dark'). تؤدي القيم غير الصالحة إلى إصدار INVALID_OPTIONS عبر الحدث error. بما أن init يطبّق مظهره الخاص دائمًا (ويستخدم 'auto' افتراضيًا)، فمرّر المظهر الأولي في init بدلًا من استدعاء setTheme قبل init.

uj.getState()

يُرجع لقطة للقراءة فقط لحالة SDK:

JavaScript
{
  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().

الحدث

البيانات

موعد الإطلاق

ready

state

اكتمل التحميل. يعيد التشغيل فورًا إذا كان قد اكتمل بالفعل.

statechange

state

عند حدوث أي تغيير في الحالة.

open

state

عندما تصبح الأداة المصغّرة مرئية.

close

state

عندما تُخفى الأداة المصغّرة.

identify

{ viewer, identityTrust }

عند تغيير الهوية، بما في ذلك تسجيل الخروج.

unread

{ count }

تغيّر عدد العناصر غير المقروءة. يعيد التشغيل فورًا إذا كانت الأداة جاهزة وتم جلب البيانات بالفعل.

presence

{ availability }

تغيّرت إتاحة الفريق بين 'online' و'neutral'. يعيد التشغيل فورًا إذا كانت الأداة جاهزة بالفعل.

error

error

عند حدوث أي خطأ في SDK.

destroy

state

عند إتلاف SDK.

يؤدي الاشتراك في unread أو presence إلى إبقاء القيمتين محدّثتين في الخلفية، حتى عندما يكون المشغّل الافتراضي مخفيًا.

uj.destroy(options?)

يزيل الأداة وكل التضمينات والجلسة من الصفحة:

JavaScript
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:

السمة

التأثير أثناء التقاط لقطة شاشة داخل الصفحة

data-userjot-capture-ignore

يستبعد العنصر تمامًا من لقطة الشاشة الملتقطة.

data-userjot-capture-mask

يحجب المحتوى المرئي للعنصر في لقطة الشاشة الملتقطة.

data-userjot-sensitive

يحجب حقول <textarea> الحساسة تلقائيًا.

الأخطاء

تكون الأخطاء بالصيغة { code, message, recoverable, cause? }.

الرمز

المعنى

INVALID_PROJECT_ID

تم استدعاء init بمعرّف مشروع فارغ.

INVALID_OPTIONS

تلقت init أو setLocale أو setTheme خيارات غير صالحة.

INVALID_NAVIGATION

تلقّى open هدفًا غير معروف أو غير صالح.

INVALID_IDENTIFY

يفتقد إدخال identify كلًا من token وuser.id.

IDENTIFY_FAILED

رفض الخادم استدعاء identify (مثلًا بسبب رمز غير صالح، أو توقيع مفقود في الوضع الصارم، أو تعارض 409، أو تجاوز حدّ المعدل، أو محو العضو).

BOOTSTRAP_FAILED

تعذّر تحميل SDK. تحقق من معرّف المشروع وقواعد CSP والاتصال بالشبكة.

NOT_READY

تم تنفيذ استدعاء بينما كان SDK في حالة فشل.

WIDGET_DISABLED

تم استدعاء open بينما كانت الأداة معطّلة.

CONVERSATIONS_DISABLED

المراسلة معطّلة لمساحة العمل هذه. تفتح الأداة الصفحة الرئيسية بدلًا من ذلك.

HELP_DISABLED

مركز المساعدة غير منشور لمساحة العمل هذه. تفتح الأداة الصفحة الرئيسية بدلًا من ذلك.

LAUNCHER_NOT_FOUND

عنصر launcher.selector غير موجود.

SIDEBAR_LOAD_FAILED

تعذّر تحميل واجهة الأداة.

EMBED_CONTAINER_NOT_FOUND

حاوية التضمين غير موجودة.

DESTROYED

تم تنفيذ استدعاء بعد destroy().

UNKNOWN

أي شيء آخر.

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