Управление виджетом

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

Эта статья ответила на ваш вопрос?