التحكم في الأداة

Shayan Taslimتم التحديث

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

فتح الأداة

يؤدي استدعاء uj.open() دون وسيطات إلى فتح الودجت في الموضع الذي تركه فيه المستخدم:

JavaScript
uj.open();

مرّر وجهة لفتح قسم محدد:

JavaScript
uj.open({ to: 'home' });
uj.open({ to: 'feedback' });
uj.open({ to: 'roadmap' });
uj.open({ to: 'updates' });
uj.open({ to: 'messages' });
uj.open({ to: 'notifications' });
uj.open({ to: 'help' });

خيارات الروابط العميقة للوجهات المحددة:

JavaScript
// Open the feedback submission form directly
uj.open({ to: 'feedback', compose: true });

// Open a specific feedback post
uj.open({ to: 'feedback', submissionId: 'POST_ID' });

// Open a specific changelog update
uj.open({ to: 'updates', updateId: 'UPDATE_ID' });

// Start a message with prefilled text
uj.open({ to: 'messages', compose: { text: 'I need help with...' } });

// Open a help article, collection, or search results
uj.open({ to: 'help', article: 'reset-password' });
uj.open({ to: 'help', collection: 'billing' });
uj.open({ to: 'help', query: 'invoices' });

أخفِ الودجت أو بدّل حالته في أي وقت:

JavaScript
uj.close();
uj.toggle();

تتطلب الوجهة messages تفعيل المحادثات؛ وإلا فستُبلّغ عن CONVERSATIONS_DISABLED عبر الحدث error، وسيُفتح قسم الصفحة الرئيسية. وتتطلب الوجهة help أن يكون مركز المساعدة منشورًا (article وcollection يأخذان المعرّف النصي للعنوان URL)؛ وإلا فستُبلّغ عن HELP_DISABLED، وسيُفتح قسم الصفحة الرئيسية.

الاستماع إلى الأحداث

اشترك باستخدام uj.on(event, listener)، الذي يعيد دالة لإلغاء الاشتراك:

JavaScript
const unsubscribe = uj.on('open', () => {
  console.log('widget opened');
});

unsubscribe();

الحدث

متى يقع

ready

اكتمل تحميل SDK. ويقع الحدث فورًا إذا كان قد تم تحميله بالفعل.

open

أصبحت الأداة ظاهرة.

close

تم إخفاء الأداة.

identify

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

unread

تغيّر عدد العناصر غير المقروءة. الحمولة هي { count }. يُعاد تشغيل الحدث فورًا إذا كان الودجت جاهزًا بالفعل.

presence

تغيّرت حالة توفر الفريق. الحمولة هي { availability: 'online' | 'neutral' }. يُعاد تشغيل الحدث فورًا إذا كان الودجت جاهزًا بالفعل.

statechange

تغيّر أي جزء من حالة الأداة.

error

حدث خطأ ما. الحمولة هي كائن الخطأ.

قراءة الحالة

تعيد uj.getState() لقطة لحالة الودجت الحالية:

JavaScript
const state = uj.getState();

state.status;          // 'ready' once the SDK is loaded
state.widget.open;     // whether the widget is visible
state.unreadCount;     // number, or null before the first fetch
state.presence;        // 'online' or 'neutral'
state.session.status;  // 'anonymous', 'identifying', or 'identified'
state.session.viewer;  // the identified user, or null

إنشاء زر تشغيل خاص بك

أخفِ المشغّل الافتراضي للتحكم في الودجت من عنصر التنقل أو الزر الخاص بك:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false }
});

يؤدي إخفاء المشغّل إلى إزالة الزر الافتراضي، مع إبقاء التنبيهات الوجيزة نشطة في الزاوية (راجع قسم التنبيهات الوجيزة أدناه لإزاحتها أو تعطيلها).

اربط الزر وشارة العناصر غير المقروءة ومؤشر توفر الفريق الاختياري:

JavaScript
const button = document.querySelector('#feedback-button');
const badge = document.querySelector('#feedback-badge');
const dot = document.querySelector('#feedback-online-dot');

button.addEventListener('click', () => uj.toggle());

uj.on('unread', ({ count }) => {
  badge.textContent = count > 0 ? String(count) : '';
});

uj.on('presence', ({ availability }) => {
  dot.hidden = availability !== 'online';
});

تعني 'neutral' أن حزمة تطوير البرامج لا تستطيع تأكيد أن أحد موظفي الدعم متصل حاليًا، لذا أخفِ المؤشر بدلًا من عرض تسمية «غير متصل». عندما يكون الودجت مغلقًا، تتجدد بيانات الحضور عند تحميل الصفحة، وعند التركيز على علامة التبويب، وكل بضع دقائق؛ أما عندما يكون مفتوحًا، فتُحدّث مباشرةً.

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

لربط سلوك المشغّل الافتراضي مباشرةً بعنصر موجود في صفحتك، مرّر محدد CSS:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: { selector: '#feedback-button' } }
});

التلميحات

الهمسات هي إشعارات منبثقة قصيرة وقابلة للنقر تظهر في زاوية الشاشة، وتعلن عن ردود غير مقروءة في محادثات الفريق، وإشعارات الملاحظات، ومنشورات جديدة في سجل التغييرات. ويكون ترتيب الأولوية كالتالي: الردود غير المقروءة على المحادثات أولًا، ثم إشعارات التعليقات والردود على الملاحظات، ثم الإشعارات الأخرى، ثم تحديثات سجل التغييرات. حفاظًا على الخصوصية، لا تعرض همسات المحادثات سوى الصورة الرمزية لعضو الفريق و<Name> replied (ولا تعرض نص الرسالة مطلقًا)، ويؤدي النقر عليها إلى فتح الرسائل.

  • حداثة العناصر والتوقيت: لا تظهر الهمسات إلا للعناصر التي أُنشئت أو نُشرت خلال آخر 14 يومًا. ينتظر الويدجت حدوث نشاط فعلي من المستخدم، ثم 4 ثوانٍ على الصفحة، و1.2 ثانية من السكون، ومرور 30 ثانية على الأقل منذ الهمسة السابقة. لا تقاطع الهمسات المستخدم أبدًا أثناء الكتابة في حقل إدخال أو مساحة نصية أو قائمة اختيار أو حقل قابل للتحرير، ولا تظهر داخل المتصفحات الآلية.

  • حدود التكرار والتأخير التدريجي: تظهر الهمسة لكل عنصر بحد أقصى 3 مرات تم تسليمها (ويُشترط ظهورها للمستخدم بانتباه لمدة 1.5 ثانية لاحتسابها كأنها سُلّمت)، مع زيادة فترة الانتظار إلى 30 دقيقة، ثم 24 ساعة، ثم 3 أيام للتحديثات، أو إلى 30 دقيقة، ثم ساعة واحدة، ثم 24 ساعة للإشعارات والردود على المحادثات.

  • مع المشغّل الافتراضي أو من دونه: الهمسات مستقلة عن المشغّل. عند استخدام المشغّل الافتراضي، تنبثق الهمسات من الزر؛ أما مع launcher: false أو مشغّل محدد بواسطة أداة اختيار، فتظهر الهمسات منفردة في الزاوية، ثم تنكمش إلى دائرة ثابتة قابلة للنقر لمدة 60 ثانية بعد انتهاء المهلة، قبل أن تختفي.

أزِح التنبيهات الوجيزة لتبتعد عن عناصر واجهتك باستخدام offset:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    launcher: false,
    offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
  }
});

أو عطّل الهمسات بالكامل (لإيقاف همسات المحادثات والملاحظات والتحديثات الافتراضية):

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false, whispers: false }
});

عند تعطيل الخيارين وعدم تحديد وضع للتحديثات، لن يعرض الودجت أي شيء حتى تستدعي uj.open()، بينما تواصل الاشتراكات unread وpresence التحديث في الخلفية.

الإعلان عن التحديثات

تحكّم في طريقة إعلان الودجت عن أحدث إدخال غير مُشاهَد في سجل التغييرات باستخدام widget.notifications.updates:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    notifications: { updates: 'full' }
  }
});

النمط

السلوك

'whisper'

يعلن عن التحديث في إشعار منبثق في الزاوية، مع فرض حدود لتكرار العرض.

'full'

يفتح التحديث مباشرةً في قارئ الودجت، مع صورة الغلاف والمحتوى الكامل.

'none'

يمنع إعلانات التحديثات مع إبقاء علامة تبويب التحديثات وشارة العناصر غير المقروءة نشطتين.

إذا لم تُحدّد قيمة، فستكون التحديثات افتراضيًا 'whisper' (أو 'none' عند whispers: false). يؤدي تعيين widget.notifications.updates صراحةً إلى تجاوز whispers لتحديثات سجل التغييرات فقط؛ أما همسات المحادثات والملاحظات فستظل تتبع whispers.

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

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

تغيير اللغة

عند عدم تحديد locale، يختار الودجت اللغة وفق الترتيب التالي:

  1. خيار locale صريح يُمرّر إلى uj.init(...) أو uj.setLocale(...).

  2. لغة متصفح الزائر، إذا كانت تطابق إحدى اللغات المفعّلة في مساحة عملك ضمن الإعدادات ← اللغات.

  3. اللغة الافتراضية لمساحة عملك.

يدعم الودجت جميع لغات UserJot الـ14 (راجع اللغات). يمكنك تغيير اللغة عند التهيئة أو أثناء التشغيل دون إعادة التحميل:

JavaScript
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });

// Change later at runtime
await uj.setLocale('pt-BR');

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