Управление виджетом
Вы можете управлять виджетом программно из собственного интерфейса: открывать определённые разделы, реагировать на события, настраивать объявления об обновлениях или полностью заменить лаунчер по умолчанию.
Открытие виджета
Вызов 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 необходимо включить раздел «Беседы». В противном случае событие error сообщит об ошибке CONVERSATIONS_DISABLED, а откроется главная страница. Для цели 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');