Виджет на сайте

Быстрая установка

В панели → Каналы → Подключение скопируйте сниппет с вашим Site ID (wgt_…). Вставьте перед </body>.

<!-- Sapportly Widget -->
<script>window.Sapportly=window.Sapportly||{q:[]};</script>
<script
  src="https://staging-cdn.sapportly.pro/sapportly.widget.js?v=b76e2df86174"
  data-site-id="wgt_..."
  data-api-url="https://staging-api.sapportly.pro"
  async
></script>

@sapportly/widget-sdk

NPM-пакет с обёртками для React, Next.js, Vue и Svelte. Подключение в одну строку — без ручной работы со скриптами и bootstrap. Имя на npm — @sapportly/widget-sdk(org sapportly), не @supportly/widget-sdk. Продукт и виджет — Sapportly (Site ID wgt_…, window.Sapportly).

npm install @sapportly/widget-sdk

pnpm add @sapportly/widget-sdk

yarn add @sapportly/widget-sdk

bun add @sapportly/widget-sdk

Vanilla / любой фреймворк

import { installWidget } from "@sapportly/widget-sdk";

const widget = await installWidget("wgt_...");
await widget.open();

React

import { SapportlyWidget } from "@sapportly/widget-sdk/react";

export function App() {
  return <SapportlyWidget siteId="wgt_..." />;
}

Next.js (env)

Задайте NEXT_PUBLIC_SAPPORTLY_SITE_ID=wgt_… (канон; legacy NEXT_PUBLIC_SUPPORTLY_SITE_ID в @sapportly/widget-sdk; хосты — *.sapportly.pro) и используйте SapportlyScriptFromEnv в client layout.

import { SapportlyScriptFromEnv } from "@sapportly/widget-sdk/next";

<SapportlyScriptFromEnv />

Полная документация SDK — в README пакета.

Как это устроено

1. JS Shell (~4 KB) — POST /v1/widget/bootstrap, тема, кнопка чата, visitor JWT в памяти.
2. WASM Core — при первом открытии: история, WebSocket (ws_ticket), сообщения, E2EE.
3. Пресеты — Каналы → Конфигуратор; конфиг и ETag приходят в bootstrap-ответе.
4. Origin allowlist — в Каналы → Подключение задаются разрешённые домены для bootstrap.

Программный API (embed)

После загрузки скрипта доступен глобальный объект:

await window.Sapportly.ready;
window.Sapportly.open();
window.Sapportly.close();
window.Sapportly.toggle();
window.Sapportly.destroy();
window.Sapportly.reloadConfig(); // после смены пресета в панели

window.Sapportly.on("security_changed", (detail) => {
  console.log("E2EE status", detail);
});

Headless (без UI)

Для серверных интеграций или кастомного UI — client.widget из @sapportly/sdk (или внутренний createWidgetClient в монорепо):

• Браузер: { siteId: "wgt_..." } → bootstrap
• Server BFF: { apiKey: "sk_live_..." } → POST /v1/widget/embed-session (право widget:embed:issue)

Аналитика

События widget.opened, widget.session_started, widget.message_sent записываются, если в Настройки → Проект → Обработка включён модуль Метрики.

CSP

Если на сайте включён Content-Security-Policy, разрешите CDN скрипта, API и WebSocket — иначе браузер заблокирует виджет. Это заголовок вашего сайта, не настройка Sapportly. Пошагово для HTML, Next.js, Nginx, Cloudflare, Tilda и WordPress: CSP виджета.

Демо

На demo.sapportly.pro можно указать Site ID из панели.

Проверка

В панели → Каналы → Подключение: статус API, CDN, WebSocket и готовый сниппет. Оформление пресетов — Каналы → Конфигуратор.

Production-чеклист

• В allowlist Origin добавлены только реальные домены сайта; * и локальные адреса не используются в production.
• API-ключ хранится только на сервере. Для BFF используйте короткоживущую embed-сессию, а не передавайте ключ в браузер, URL, логи или исходный код.
• CSP разрешает CDN, API и WebSocket Sapportly. При смене домена проверьте preflight, bootstrap и открытие сокета в браузере.
• Файлы отправляются через upload intent: изображения остаются изображениями, остальные вложения — документами. Для повторной отправки задавайте idempotency key.
• Если включено сквозное шифрование, тело сообщения доступно только участникам диалога; ключи не логируются и не передаются в систему аналитики или дайджест. Обычные вложения на E2EE-канале не принимаются — не смешивайте режимы защиты для текста и файлов.