Веб-чат-виджет

Встройте на любой сайт чат с Cradle одним script-тегом — история, typing-индикатор и ответы в реальном времени.

Веб-виджет Cradle — это полноценный чат-канал, а не форма обратной связи. Посетитель видит плавающую кнопку, открывает окно с историей сообщений, пишет сообщение и получает ответ от Cradle в реальном времени.

Размер bundle: ~49 KB gzipped.

Встраивание

Добавьте один script-тег на любую страницу:

<script
  src="https://cradle.example.com:31415/widget.js"
  data-cradle-widget
  data-api-key="wk_..."
  data-accent="#10b981"
  data-position="bottom-right"
  async></script>

Для локального тестирования используйте http://localhost:31415/widget.js.

Атрибуты конфигурации

Атрибут	Обязательный	Описание
`src`	да	URL bundle
`data-cradle-widget`	да	Маркер монтирования
`data-api-key`	да	Widget API key из конфига канала
`data-accent`	нет	Hex-цвет кнопки и кнопки отправки
`data-position`	нет	`bottom-right` (default) или `bottom-left`

Серверная тема, позиция и locale возвращаются GET /api/widget/config/:apiKey. Клиентские атрибуты переопределяют часть значений.

Архитектура

packages/widget/ — Vite IIFE bundle, React inlined.
src/core/channels/widget-channel.ts — Fastify-сервер в main process.
Shadow DOM mount изолирует стили от родительской страницы.
Нет postMessage в parent window: всё общение идёт по HTTP/WebSocket к Cradle.

Серверные endpoint'ы

Endpoint	Назначение
`GET /widget.js`	Раздача bundle с long cache
`GET /api/widget/config/:apiKey`	Тема, цвет, позиция, locale
`POST /api/widget/message`	Приём сообщения посетителя (`X-Visitor-Id`)
`WS /api/widget/ws?visitorId=...&apiKey=...`	Real-time ответы и typing

Поведение клиента

visitorId генерируется при первом открытии и хранится в localStorage.
История чата кешируется локально, перезагрузка страницы не сбрасывает диалог.
WebSocket автоматически переподключается с exponential backoff.
Показывается typing-индикатор, пока идёт ответ.

Безопасность

Widget API key задаётся в channels_config.widget.config.apiKey.
Опциональный allowedOrigins ограничивает сайты, которые могут загружать виджет.
Rate limit применяется per IP + key.
В production expose виджет endpoint через reverse proxy или tunnel и используйте HTTPS.