Справочник по SDK
SDK доступен через window.uj. Вызовы без ожидания результата, сделанные через встроенный прокси предварительной загрузки (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy), ставятся в очередь и выполняются после загрузки uj.js. Для вызовов, возвращающих значения или промисы (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version), необходимо сначала загрузить скрипт SDK.
uj.version
Строка с версией SDK, например 1.0.0.
uj.init(projectId, options?)
Инициализирует SDK. Возвращает промис, который разрешается с состоянием SDK после завершения загрузки.
const state = await uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: true, // boolean or { selector: string }
whispers: true, // default whisper behavior
notifications: { updates: 'whisper' }, // 'whisper', 'full', or 'none'
position: 'right', // 'left' or 'right'
offset: { bottom: 20 }, // corner distance in pixels: { bottom, side }
theme: 'auto' // 'auto', 'light', or 'dark'
},
locale: 'es-MX', // optional language override
pageContext: 'origin', // 'origin', 'path', or 'none'
onReady: () => {},
onError: (error) => {}
});Параметр | По умолчанию | Описание |
|---|---|---|
|
|
|
|
|
|
|
| Временные всплывающие уведомления в углу виджета. Они не зависят от кнопки запуска: продолжают появляться, даже если кнопка скрыта, если не задать |
|
|
|
|
| С какой стороны экрана открывается виджет. |
|
| Расстояние в пикселях от краёв области просмотра до кнопки запуска и всплывающих подсказок. |
|
| Следовать системной настройке или принудительно включить светлую либо тёмную тему. |
| язык браузера → язык рабочей области по умолчанию | Переопределение языка. Если параметр не указан, язык браузера посетителя сопоставляется с языками, доступными в вашей рабочей области; если совпадения нет, используется язык рабочей области по умолчанию. Поддерживаются все 14 языков UserJot; региональные теги, например |
|
| Какая часть URL текущей страницы передается вашей команде в обсуждениях и разделе Live visitors. |
| Вызывается, когда SDK готов. | |
| Вызывается при любой ошибке SDK. |
Возвращённый промис не отклоняется при проблемах с сетью (проверьте state.status === 'ready'). Он отклоняется только при ошибках программирования, например если идентификатор проекта пуст или параметры имеют неверный формат (INVALID_OPTIONS, recoverable: false).
Полный режим обновлений работает без кнопки запуска, всплывающих подсказок и подписок на события хоста. Точные правила отображения, фокуса и хранения статуса просмотра см. в разделе Уведомления об обновлениях.
uj.ready()
Возвращает тот же промис, что и init. Это полезно, если код, которому нужен SDK, находится отдельно от кода инициализации.
const state = await uj.ready();uj.identify(input)
Идентифицирует текущего пользователя. Возвращает промис с результатом. См. разделы Идентификация пользователей и Подписанная идентификация.
const result = await uj.identify({
token: 'OPTIONAL_JWT_FROM_YOUR_SERVER',
user: {
id: 'user-123', // required if no token is given
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
avatar: 'https://example.com/avatar.jpg',
traits: { plan: 'pro' }
},
companies: [
{
id: 'acme',
name: 'ACME Inc.',
domain: 'acme.com',
logo: 'https://acme.com/logo.png',
traits: { plan: 'enterprise' }
}
]
});
result.viewer; // the identified user, or null
result.identityTrust; // 'signed', 'unsigned', or null
result.warnings; // [{ code, message, field? }]viewer имеет следующую структуру:
{
id: 'mem_...', // UserJot's member ID, not the user.id you sent
firstName: 'Ada', // string or null
lastName: 'Lovelace', // string or null
avatar: { url: 'https://...', blurhash: '...' } // or null; blurhash optional
}Предупреждения и зарезервированные ключи атрибутов
Код |
| Значение |
|---|---|---|
| Ключ атрибута | Ключ зарезервирован UserJot и был отброшен. |
| Компания | Для рабочего пространства требуется подписанное членство в компании, а этой компании не было в токене. |
|
| Пользователь — администратор или владелец рабочего пространства. Его свойства и компании применяются; имя, аватар и адрес электронной почты управляются в панели управления. |
Следующие ключи атрибутов зарезервированы и игнорируются (при этом генерируется RESERVED_TRAIT_KEY_IGNORED): id, externalId, external_id, email, name, firstName, first_name, lastName, last_name, avatar, avatarUrl, avatar_url, role, type, companies, company, companyId, company_id, createdAt, created_at, updatedAt, updated_at, deletedAt, deleted_at и __proto__.
Требуется указать хотя бы одно из значений: token или user.id. Повторный вызов identify с теми же данными ничего не делает, пока сессия активна; после ее завершения те же данные отправят новый запрос. Вызов с новыми данными переключает сессию. Если несколько вызовов выполняются одновременно, действует последний. Только метод identify отклоняет промисы при ошибках во время выполнения (IDENTIFY_FAILED), а также устанавливает локальную паузу после ответов HTTP 429 (с учетом Retry-After, от 1 секунды до 1 часа; по умолчанию — 60 секунд).
uj.logout()
Сбрасывает текущую идентичность и возвращает сессию в анонимное состояние.
await uj.logout();uj.open(target?)
Открывает виджет. Если аргумент не указан, открывает его на том месте, где пользователь остановился. Промис разрешается, когда виджет становится видимым.
await uj.open();
await uj.open({ to: 'home' });
await uj.open({ to: 'feedback' });
await uj.open({ to: 'feedback', compose: true });
await uj.open({ to: 'feedback', submissionId: 'POST_ID' });
await uj.open({ to: 'roadmap' });
await uj.open({ to: 'updates' });
await uj.open({ to: 'updates', updateId: 'UPDATE_ID' });
await uj.open({ to: 'messages' });
await uj.open({ to: 'messages', compose: { text: 'Prefilled message' } });
await uj.open({ to: 'notifications' });
await uj.open({ to: 'help' });
await uj.open({ to: 'help', article: 'ARTICLE_SLUG' });
await uj.open({ to: 'help', collection: 'COLLECTION_SLUG' });
await uj.open({ to: 'help', query: 'Search text' });Для цели help можно указать не более одного из значений article, collection или query. Для article и collection используется URL-слаг, а старые слаги перенаправляют на перемещённую страницу. Промис отклоняется с ошибкой INVALID_NAVIGATION при неизвестной цели или недопустимом сочетании параметров.
uj.close()
Скрывает виджет. Выполняется синхронно, можно безопасно вызывать в любое время.
uj.toggle()
Открывает виджет, если он закрыт, и закрывает, если он открыт.
uj.createEmbed(options?)
Отображает страницу UserJot внутри контейнера на вашей странице. Возвращает контроллер. См. раздел Встраивание страниц непосредственно на сайт.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
Меняет язык виджета во время работы:
await uj.setLocale('pt-BR');uj.setTheme(theme)
Синхронно меняет тему виджета ('auto', 'light' или 'dark'). При недопустимых значениях генерируется INVALID_OPTIONS через событие error. Поскольку init всегда применяет собственную тему (по умолчанию 'auto'), задайте начальную тему в init, а не вызывайте setTheme перед init.
uj.getState()
Возвращает снимок состояния SDK, доступный только для чтения:
{
status: 'ready', // 'idle' | 'initializing' | 'ready' | 'error' | 'destroyed'
projectId: 'proj_...',
locale: 'en-US',
unreadCount: 3, // number, or null before the first fetch
presence: 'online', // 'online' | 'neutral'
lastError: null,
widget: {
enabled: true,
open: false,
position: 'right',
theme: 'auto'
},
session: {
status: 'identified', // 'anonymous' | 'identifying' | 'identified'
identityTrust: 'signed',
viewer: { id: 'mem_...', firstName: 'Ada', lastName: 'Lovelace', avatar: null }
}
}uj.on(event, listener)
Подписывается на событие и возвращает функцию отмены подписки. Обработчики сохраняются после destroy().
Событие | Данные события | Когда срабатывает |
|---|---|---|
| состояние | Загрузка завершена. Если загрузка уже завершилась, событие воспроизводится немедленно. |
| состояние | При любом изменении состояния. |
| состояние | Виджет стал видимым. |
| состояние | Виджет был скрыт. |
|
| Идентичность изменилась, в том числе при выходе из системы. |
|
| Изменилось количество непрочитанных сообщений. Если SDK уже готов и данные загружены, событие воспроизводится немедленно. |
|
| Доступность команды изменилась с |
| ошибка | При любой ошибке SDK. |
| состояние | SDK был уничтожен. |
Подписка на unread или presence обеспечивает актуальность обоих значений в фоновом режиме, даже если кнопка запуска по умолчанию скрыта.
uj.destroy(options?)
Удаляет со страницы виджет, все встроенные элементы и сессию:
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData также удаляет локальные разрешения на анонимные переписки, черновики и сохранённые контактные данные (полезно на устройствах общего пользования).
Атрибуты DOM для создания скриншотов
Когда пользователь делает скриншот страницы из формы отзыва в виджете (резервный вариант захвата DOM), UserJot автоматически скрывает элементы интерфейса виджета и маскирует input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] и input[name*="secret" i]. Также можно управлять захватом отдельных элементов с помощью атрибутов HTML:
Атрибут | Действие при создании скриншота страницы |
|---|---|
| Полностью исключает элемент из создаваемого скриншота. |
| Скрывает видимое содержимое элемента на создаваемом скриншоте. |
| Автоматически маскирует чувствительные поля |
Ошибки
Ошибки имеют формат { code, message, recoverable, cause? }.
Код | Значение |
|---|---|
| Вызов |
| Для |
| Для |
| Во входных данных |
| Сервер отклонил вызов identify (например, из-за недействительного токена, отсутствующей подписи в строгом режиме, конфликта |
| Не удалось загрузить SDK. Проверьте идентификатор проекта, правила CSP и подключение к сети. |
| Вызов выполнен, когда SDK находился в состоянии сбоя. |
| Метод |
| В этой рабочей области обмен сообщениями отключён. Вместо этого виджет открывает главную страницу. |
| Справочный центр этой рабочей области ещё не опубликован. Вместо этого виджет открывает главную страницу. |
| Элемент |
| Не удалось загрузить интерфейс виджета. |
| Контейнер для встраивания не существует. |
| Вызов выполнен после |
| Всё остальное. |