Керування віджетом

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' означає, що SDK не може підтвердити, чи оператор зараз онлайн, тому приховайте індикатор замість того, щоб показувати статус «не в мережі». Коли віджет закрито, статус присутності оновлюється під час завантаження сторінки, перемикання фокуса на вкладку та кожні кілька хвилин; коли віджет відкрито — оновлюється в реальному часі.

У стандартному лаунчері індикатор непрочитаних має пріоритет над зеленою крапкою статусу «онлайн». Лічильник непрочитаних охоплює відповіді в розмовах, дописи в журналі змін і сповіщення про відгуки. Якщо натиснути стандартний лаунчер, коли є непрочитані елементи, відкриється розділ у такому порядку пріоритетності: Повідомлення (непрочитані відповіді в розмовах), потім Сповіщення (непереглянуті сповіщення про відгуки), а потім останнє непереглянуте Оновлення.

Щоб прив’язати стандартну поведінку елемента запуску безпосередньо до наявного елемента на сторінці, передайте 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 хвилин, 1 година та 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.

Повний режим працює, навіть якщо елемент запуску приховано й немає слухачів подій. Під час першого відвідування повний режим може відкрити останнє опубліковане оновлення, навіть якщо воно давніше. SDK намагається автоматично відкрити віджет не більше одного разу за відвідування, під час якого його ініціалізовано (ручне відкриття, перемикання, закриття або невдала спроба використовує цю можливість; перезавантаження сторінки або виклик init() починає нове відвідування, а зміни ідентичності чи навігація в SPA — ні). Автоматичне відкриття потребує видимої сторінки у фокусі та закритого віджета; його вимкнено, коли widget: false.

Оновлення позначається як переглянуте, щойно його вміст відображається у відкритому віджеті на видимій сторінці у фокусі. Статус перегляду зберігається локально у сховищі браузера окремо для кожного проєкту й джерела. Оновлення виявляються під час ініціалізації, коли вкладка отримує фокус і приблизно кожні п’ять хвилин, поки віджет закрито.

Зміна мови

Якщо параметр locale не задано, віджет вибирає мову в такому порядку:

  1. Явно заданий параметр locale, переданий у uj.init(...) або uj.setLocale(...).

  2. Мова браузера відвідувача, якщо вона збігається з однією з мов робочого простору, увімкнених у розділі Налаштування → Мови.

  3. Мова робочого простору за замовчуванням.

Віджет підтримує всі 14 мов UserJot (див. розділ Мови). Змініть мову під час ініціалізації або під час роботи, не перезавантажуючи сторінку:

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

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

Чи відповіла ця стаття на ваше запитання?