Widget

Чат-виджет — это один скрипт-тег, который можно вставить на любую страницу. Он создаёт плавающую кнопку в углу, открывает чат с оператором, тянет ленту сообщений и историю тикетов. Никакой установки или авторизации клиенту не нужно.

Минимальная установка

<script>
(function(w, d){
  function loadWidget(token){
    var s = d.createElement('script');
    s.async = 1;
    s.src = 'https://support.forestsnet.com/widget-bundle?ws=WORKSPACE_UUID';
    if (token) s.setAttribute('data-visitor-token', token);
    d.head.appendChild(s);
  }
  // Optional cross-device identity: fetch a signed token from your
  // backend. Drop the fetch + just call loadWidget() if you don't
  // need cross-device. Endpoint format: see /docs/widget/identify.
  fetch('/api/supporthub/token', { credentials: 'include' })
    .then(function(r){ return r.ok ? r.json() : null; })
    .then(function(data){ loadWidget(data && data.token); })
    .catch(function(){ loadWidget(); });
})(window, document);
</script>

Атрибуты тега

Передача данных пользователя

Если ваш сайт уже знает посетителя — передайте поля прямо в тег. Виджет создаст / обновит контакт на бэке через POST /widget/identifyавтоматически при загрузке (даже если посетитель ещё не открывал чат).

Когда нужны data-* атрибуты — используйте прямой <script async> вместо loader-сниппета. IIFE-loader создаёт тег без вашей атрибутики, бандл прочитать её не сможет.

<script
  async
  src="https://support.forestsnet.com/widget-bundle?ws=WORKSPACE_UUID"
  data-email="{{ user.email }}"
  data-name="{{ user.full_name }}"
  data-phone="{{ user.phone }}"
  data-telegram-id="{{ user.telegram_id }}"
></script>

Динамическая идентификация из JS

Если пользователь логинится после загрузки страницы (SPA), вызовите window.SupportHub.identify(). Он экспортируется ещё до завершения init() — вызовы до загрузки бандла буферизуются и отправляются автоматически как только виджет инициализируется.

// После того как юзер вошёл в аккаунт:
window.SupportHub.identify({
  email: user.email,
  name: user.fullName,
  phone: user.phone,
  telegram_id: user.telegramId,
});

Поля совпадают с data-*-атрибутами. Передавайте только то что знаете — пустые поля не затирают существующие значения. Email при повторном identify обновится (раньше был хард-409 при попытке сменить email — это исправлено в d62e0ef).

Хранение visitor session

ID визитора (vs_<random>) — единственное что привязывает анонимную сессию к контакту в БД. Чтобы он переживал Safari ITP, private mode, перезагрузки страницы и закрытие вкладок, виджет хранит его параллельно в пяти местах:

Read precedence: 1 → 2 → 3 → 5. Первое непустое значение побеждает; затем оно зеркалируется во все доступные tier'ы, так что если в одной браузерной сессии cookie был выкинут ITP, при следующей загрузке value поднимается из localStorage и записывается обратно в cookie. IndexedDB пишется fire-and-forget — потерять запись туда не страшно, sync tier'ы уже держат значение.

Cross-tab sync

BroadcastChannel('sh-widget-sync') уведомляет другие вкладки в том же браузере как только session id создан или промотирован — две одновременно открытые вкладки не сгенерируют два параллельных id. Когда BroadcastChannel недоступен (Firefox private mode), используется fallback через storage-event на window (он firing'ится в OTHER вкладках при изменении localStorage).

Один визитор на нескольких поддоменах

По умолчанию tier 1 (cookie) scoped по host: визитор на example.com и app.example.com — два разных контакта, две беседы. Tiers 2–5 тоже scoped per-origin — cross-subdomain работает только через cookie с явно указанным доменом.

Чтобы сохранять одну беседу между корневым доменом и поддоменами, задайте cookie-домен с точкой в начале:

• Через админку: «Конструктор виджета → Поведение → Домен cookie» → ввести .example.com. Снипет на всех поддоменах остаётся тем же — виджет прочитает значение из конфига.
• Через атрибут: data-cookie-domain=".example.com"в теге <script>. Атрибут выигрывает у конфига — удобно если стейдж и прод на разных доменах.

Миграция автоматическая: при первом заходе виджет читает старый localStorage-ключ sh-visitor-session и переписывает значение в cookie с указанным доменом. На следующем поддомене браузер найдёт cookie и подхватит ту же сессию.

JS controller API

После загрузки бандла на window.SupportHub доступен controller с публичным API. Методы безопасно вызывать до завершения init() — bundle экспортирует init и identify сразу при загрузке скрипта; вызовы до init буферизуются и выполняются как только controller онлайн.

Lifecycle / порядок инициализации

1. Bundle грузится через <script src=".../widget-bundle?ws=...">. При загрузке IIFE auto-boot:
   • Pin'ит window.__SH_API_BASE из data-api-base или script origin (см. preamble).
   • Скрейпит data-* атрибуты в _identifyState.
   • Если ?ws= в URL — вызывает initInternal().
2. initInternal():
   • Загружает конфиг (либо из preamble __SH_WIDGET_CONFIG, либо GET /webhooks/widget/{ws}/config).
   • Создаёт shell, state, api client.
   • primeFromIndexedDB — async-восстановление session из IDB если все sync tier'ы пусты.
   • openVisitorWs — opportunistic WS connect (4401 пока нет Contact'а).
   • flushIdentify — POST в /widget/identify если есть pending данные.
   • subscribeSessionSync — cross-tab BroadcastChannel listener.
3. Controller возвращается из init() и присваивается в window.SupportHub. Дальнейший SupportHub.identify(...) работает через тот же controller.

Глобалы которые виджет ставит на window

• window.SupportHub — controller (методы выше)
• window.__SH_API_BASE — base URL API (pinned из script tag origin или preamble)
• window.__SH_WIDGET_CONFIG — заинлайненный конфиг (только если bundle серверу удалось pre-fetch)
• window.__SH_WIDGET_V2_MOUNTED — guard от двойного auto-boot

WebSocket protocol

После Contact'a создания виджет открывает wss://api.support.forestsnet.com/api/ws/widget/{visitor_session}?workspace_id={ws} (плюс &signed_token=... для cross-device). Backend пушит JSON-фреймы:

• { type: "message.created", data: { ticket_id, content, ... } } — новое сообщение от оператора
• { type: "ticket.assigned", data: { ticket_id, operator_name, operator_avatar_url } } — оператор взял тикет
• { type: "ticket.transferred", data: { ticket_id, from, to } } — передача между операторами
• { type: "message.reaction.added"|"removed", data: { message_id, emoji } }
• { type: "operator_seen", data: { ticket_id, last_seen_message_id } } — оператор открыл тикет
• { type: "operator_typing", data: { ticket_id, is_typing } }

Visitor-side ping/pong каждые ~30s — иначе backend закрывает connection через 60s неактивности (и помечает offline в ContactChannelStatus).

Расширение через events

Если нужно реагировать на события виджета (открытие чата, отправка сообщения) из своего кода — используйте webhooks API на бекенде (/docs/api-guide/webhooks). Public DOM-events на стороне клиента в текущей версии не эмитятся — это в roadmap (SupportHub.on('open', cb) планируется).