Керування віджетом
Ви можете програмно керувати віджетом зі свого інтерфейсу: відкривати певні розділи, реагувати на події, налаштовувати анонси оновлень або повністю замінити стандартний елемент запуску.
Відкриття віджета
Виклик uj.open() без аргументів відкриває віджет у тому місці, де користувач зупинився:
uj.open();Передайте ціль, щоб відкрити певний розділ:
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' });Параметри глибоких посилань для певних цілей:
// 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' });Приховуйте віджет або перемикайте його видимість у будь-який час:
uj.close();
uj.toggle();Для цілі messages потрібно ввімкнути «Розмови»; інакше вона повідомить про CONVERSATIONS_DISABLED через подію error та відкриє головну сторінку. Для цілі help Центр довідки має бути опублікований (article і collection приймають URL-частину адреси); інакше вона повідомить про HELP_DISABLED та відкриє головну сторінку.
Прослуховування подій
Підпишіться за допомогою uj.on(event, listener), який повертає функцію скасування підписки:
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Подія | Коли вона спрацьовує |
|---|---|
| SDK завершив завантаження. Якщо завантаження вже завершилося, подія спрацьовує відразу. |
| Віджет став видимим. |
| Віджет було приховано. |
| Ідентифікаційні дані змінилися, зокрема під час виходу з облікового запису. |
| Кількість непрочитаних змінилася. Дані: |
| Доступність команди змінилася. Дані: |
| Змінилася будь-яка частина стану віджета. |
| Сталася помилка. Дані — об’єкт помилки. |
Отримання стану
uj.getState() повертає знімок поточного стану віджета:
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Створення власної кнопки запуску
Приховайте стандартний елемент запуску, щоб керувати віджетом за допомогою власного пункту навігації або кнопки:
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false }
});Якщо приховати елемент запуску, стандартна кнопка зникне, але кутові сповіщення залишаться активними (див. розділ «Сповіщення» нижче, щоб змістити їх або вимкнути).
Налаштуйте кнопку, значок непрочитаних і, за бажанням, індикатор доступності команди:
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-селектор:
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:
uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: false,
offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
}
});Або повністю вимкніть сповіщення (про розмови, відгуки та оновлення за замовчуванням):
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false, whispers: false }
});Якщо вимкнути обидва параметри й не вказати режим оновлень, віджет нічого не відображатиме, доки ви не викличете uj.open(). Водночас підписки unread і presence продовжать оновлюватися у фоновому режимі.
Сповіщення про оновлення
За допомогою widget.notifications.updates налаштуйте, як віджет повідомлятиме про найновіший непрочитаний запис журналу змін:
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Режим | Поведінка |
|---|---|
| Повідомляє про оновлення у вигляді кутового сповіщення з обмеженням повторів. |
| Безпосередньо відкриває оновлення у вікні читання віджета — із зображенням обкладинки та повним вмістом. |
| Приховує сповіщення про оновлення, але залишає активними вкладку «Оновлення» та значок непрочитаних. |
Якщо не вказано, для оновлень використовується значення 'whisper' (або 'none', якщо whispers: false). Явне налаштування widget.notifications.updates перевизначає whispers лише для оновлень журналу змін; сповіщення про розмови й відгуки й надалі визначаються параметром whispers.
Повний режим працює, навіть якщо елемент запуску приховано й немає слухачів подій. Під час першого відвідування повний режим може відкрити останнє опубліковане оновлення, навіть якщо воно давніше. SDK намагається автоматично відкрити віджет не більше одного разу за відвідування, під час якого його ініціалізовано (ручне відкриття, перемикання, закриття або невдала спроба використовує цю можливість; перезавантаження сторінки або виклик init() починає нове відвідування, а зміни ідентичності чи навігація в SPA — ні). Автоматичне відкриття потребує видимої сторінки у фокусі та закритого віджета; його вимкнено, коли widget: false.
Оновлення позначається як переглянуте, щойно його вміст відображається у відкритому віджеті на видимій сторінці у фокусі. Статус перегляду зберігається локально у сховищі браузера окремо для кожного проєкту й джерела. Оновлення виявляються під час ініціалізації, коли вкладка отримує фокус і приблизно кожні п’ять хвилин, поки віджет закрито.
Зміна мови
Якщо параметр locale не задано, віджет вибирає мову в такому порядку:
Явно заданий параметр
locale, переданий уuj.init(...)абоuj.setLocale(...).Мова браузера відвідувача, якщо вона збігається з однією з мов робочого простору, увімкнених у розділі Налаштування → Мови.
Мова робочого простору за замовчуванням.
Віджет підтримує всі 14 мов UserJot (див. розділ Мови). Змініть мову під час ініціалізації або під час роботи, не перезавантажуючи сторінку:
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');