Довідник 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-адреси поточної сторінки передається вашій команді в обговореннях і розділі Відвідувачі наживо. |
| Викликається, коли 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 перебував у стані помилки. |
| Викликано |
| Для цього робочого простору вимкнено повідомлення. Віджет відкриває розділ «Головна». |
| Довідковий центр цього робочого простору ще не опубліковано. Віджет відкриває розділ «Головна». |
| Елемент |
| Не вдалося завантажити інтерфейс віджета. |
| Контейнер вбудованого елемента не існує. |
| Виклик виконано після |
| Усе інше. |