Справочник по 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 текущей страницы передается вашей команде в обсуждениях и разделе Live visitors. '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

Всё остальное.

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