Довідник SDK

Shayan TaslimОновлено

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 після завершення завантаження.

JavaScript
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) => {}
});

Параметр

За замовчуванням

Опис

widget

true

true показує віджет із параметрами за замовчуванням. false вимикає його. Об’єкт налаштовує віджет.

widget.launcher

true

false приховує кнопку за замовчуванням. { selector } прив’язує віджет до вашого елемента.

widget.whispers

true

Тимчасові сповіщення-тости в куті віджета. Не залежать від кнопки запуску: вони й надалі з’являються, коли кнопку приховано, якщо не встановити значення false. Явно заданий режим сповіщень про оновлення перевизначає це налаштування лише для оголошень у журналі змін. Див. Керування віджетом.

widget.notifications.updates

'whisper' або 'none' за умови whispers: false

'whisper' показує сповіщення про оновлення у спливаючому повідомленні; 'full' відкриває останній непрочитаний запис у засобі читання віджета; 'none' вимикає сповіщення про оновлення, але зберігає позначку «непрочитане». Явні значення перевизначають whispers лише для оновлень.

widget.position

'right'

З якого боку екрана відкривається віджет.

widget.offset

{ bottom: 20, side: 20 }

Відстань у пікселях від країв вікна перегляду до запуску віджета та коротких повідомлень.

widget.theme

'auto'

Використовувати системне налаштування або примусово ввімкнути світлу чи темну тему.

locale

браузер → мова за замовчуванням у робочому просторі

Перевизначення мови. Якщо значення не вказано, мова браузера відвідувача зіставляється з увімкненими мовами робочого простору, а за відсутності збігу використовується мова робочого простору за замовчуванням. Підтримуються всі 14 мов UserJot; регіональні теги, як-от es-MX, визначаються як відповідна мова.

pageContext

'origin'

Яка частина URL-адреси поточної сторінки передається вашій команді в обговореннях і розділі Відвідувачі наживо. 'origin' передає лише ім’я хоста, 'path' додає шлях (рядки запиту та #fragments видаляються), 'none' не передає нічого.

onReady

Викликається, коли SDK готовий.

onError

Викликається в разі будь-якої помилки SDK.

Проміс, що повертається, не відхиляється через проблеми з мережею (перевірте state.status === 'ready'). Він відхиляється лише через помилки програмування, наприклад порожній ідентифікатор проєкту або некоректні параметри (INVALID_OPTIONS, recoverable: false).

Повний режим оновлень працює без запуску віджета, коротких повідомлень і підписок хоста. Точні правила видимості, фокуса та збереження статусу перегляду див. у розділі Сповіщення про оновлення.

uj.ready()

Повертає той самий проміс, що й init. Зручно використовувати, коли код, якому потрібен SDK, розміщений окремо від коду ініціалізації.

JavaScript
const state = await uj.ready();

uj.identify(input)

Ідентифікує поточного користувача. Повертає проміс із результатом. Див. Ідентифікація користувачів і Підписана ідентичність.

JavaScript
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 має таку структуру:

JavaScript
{
  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
}

Попередження та зарезервовані ключі атрибутів

Код

field

Значення

RESERVED_TRAIT_KEY_IGNORED

Ключ атрибута

Цей ключ зарезервовано за UserJot, тому його було відкинуто.

UNSIGNED_COMPANY_IGNORED

Компанія id

Для робочого простору потрібне підписане членство в компанії, а цієї компанії не було в токені.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar або email

Користувач є адміністратором або власником робочого простору. До нього застосовуються його характеристики та дані компаній; його ім’ям, аватаром і електронною адресою керують на панелі керування.

Наведені нижче ключі атрибутів зарезервовані та ігноруються (з генеруванням події 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()

Очищає поточну ідентичність і повертає сесію до анонімного стану.

JavaScript
await uj.logout();

uj.open(target?)

Відкриває віджет. Якщо аргумент не вказано, відкриває його на тому місці, де користувач зупинився. Виклик завершується, коли віджет стає видимим.

JavaScript
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 у контейнері на вашій сторінці. Повертає контролер. Див. розділ Вбудовування сторінок у рядок.

JavaScript
const embed = uj.createEmbed({
  container: '[data-userjot-embed]',
  path: '/',
  basePath: '/feedback',
  theme: 'auto',
  onReady: () => {},
  onError: (error) => {}
});

embed.navigate('/roadmap');
embed.destroy();

uj.setLocale(locale)

Змінює мову віджета під час роботи:

JavaScript
await uj.setLocale('pt-BR');

uj.setTheme(theme)

Синхронно змінює тему віджета ('auto', 'light' або 'dark'). Для неприпустимих значень генерується подія INVALID_OPTIONS через подію error. Оскільки init завжди застосовує власну тему (за замовчуванням — 'auto'), передайте початкову тему в init, а не викликайте setTheme перед init.

uj.getState()

Повертає доступний лише для читання знімок стану SDK:

JavaScript
{
  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().

Подія

Дані

Коли спрацьовує

ready

стан

Завершення завантаження. Якщо завантаження вже завершилося, подія повторюється негайно.

statechange

стан

Будь-яка зміна стану.

open

стан

Віджет став видимим.

close

стан

Віджет було приховано.

identify

{ viewer, identityTrust }

Зміна ідентичності, зокрема вихід із системи.

unread

{ count }

Змінилася кількість непрочитаних елементів. Якщо SDK уже готовий і дані отримано, подія повторюється негайно.

presence

{ availability }

Доступність команди змінилася на протилежну: 'online' або 'neutral'. Якщо SDK уже готовий, подія повторюється негайно.

error

помилка

Будь-яка помилка SDK.

destroy

стан

SDK знищено.

Підписка на unread або presence підтримує обидва значення в актуальному стані у фоновому режимі, навіть коли запуск віджета за замовчуванням приховано.

uj.destroy(options?)

Видаляє зі сторінки віджет, усі вбудовані елементи та сеанс:

JavaScript
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-атрибутів:

Атрибут

Дія під час створення знімка екрана сторінки

data-userjot-capture-ignore

Повністю виключає елемент зі знімка екрана.

data-userjot-capture-mask

Приховує видимий вміст елемента на знімку екрана.

data-userjot-sensitive

Автоматично маскує конфіденційні поля <textarea>.

Помилки

Помилки мають формат { code, message, recoverable, cause? }.

Код

Значення

INVALID_PROJECT_ID

Викликано init з порожнім ідентифікатором проєкту.

INVALID_OPTIONS

Для init, setLocale або setTheme отримано неприпустимі параметри.

INVALID_NAVIGATION

open отримав невідомий або недійсний об’єкт.

INVALID_IDENTIFY

У виклику identify відсутні і token, і user.id.

IDENTIFY_FAILED

Сервер відхилив виклик identify (наприклад, через недійсний токен, відсутній підпис у режимі суворої перевірки, конфлікт 409, обмеження частоти запитів або видаленого учасника).

BOOTSTRAP_FAILED

Не вдалося завантажити SDK. Перевірте ідентифікатор проєкту, правила CSP і мережеве з’єднання.

NOT_READY

Виклик виконано, коли SDK перебував у стані помилки.

WIDGET_DISABLED

Викликано open, коли віджет вимкнено.

CONVERSATIONS_DISABLED

Для цього робочого простору вимкнено повідомлення. Віджет відкриває розділ «Головна».

HELP_DISABLED

Довідковий центр цього робочого простору ще не опубліковано. Віджет відкриває розділ «Головна».

LAUNCHER_NOT_FOUND

Елемент launcher.selector не існує.

SIDEBAR_LOAD_FAILED

Не вдалося завантажити інтерфейс віджета.

EMBED_CONTAINER_NOT_FOUND

Контейнер вбудованого елемента не існує.

DESTROYED

Виклик виконано після destroy().

UNKNOWN

Усе інше.

Чи відповіла ця стаття на ваше запитання?