Social Floating Builder — документация по API и встраиванию

Версия сервиса: 0.0.1 (Social Floating Service, 2025-11-22) Базовый шлюз: http://127.0.0.1:3500 → проксирует http://127.0.0.1:3402.

Ключевая идея: вы создаёте конфигурацию набора кнопок (цвета, расположение, триггеры показа), публикуете её и внедряете один тег на любой сайт. Сервис бесплатный, не требует авторизации для embed-скрипта и событий.

1. Быстрый старт

pnpm install
pnpm --filter @saas-apps/service-social-floating dev
pnpm --filter @saas-apps/gateway dev

Gateway отдаёт SPA по http://127.0.0.1:3500/app и проксирует /api/v1/social-floating/*.
Сервис стартует на http://127.0.0.1:3402, при первом запуске создаёт демо-конфиг (можно отключить SOC_SEED_DEMO=0).
HTML-админка: http://127.0.0.1:3402/admin (или /api/v1/social-floating/admin через gateway). Если задан API_KEY, требуется заголовок x-api-key.

Переменные окружения

Переменная	Значение по умолчанию	Описание
`PORT` / `HOST`	`3402` / `127.0.0.1`	Где слушает сервис.
`API_KEY`	пусто	Если указан, приватные маршруты (`/admin`, `/api/**`) требуют `x-api-key`. Embed и `/events` остаются публичными.
`SOC_STORE`	`memory`	Хранилище: `memory` или `file`.
`SOC_FILE_PATH`	`./data/social-floating.json`	Путь до JSON, если `SOC_STORE=file`. Можно также использовать `FILE_STORE_PATH`/`DB_PATH`.
`GATEWAY_URL`	`http://127.0.0.1:3500`	URL, который вставляется в сниппет/админку.
`SOC_SEED_DEMO`	`1`	`0` — не создавать демо-конфиг при старте.

2. API конфигураций

База через gateway: http://127.0.0.1:3500/api/v1/social-floating (напрямую: http://127.0.0.1:3402).

Метод	Путь	Описание
`GET`	`/api/configs`	Список конфигов (id, имя, версия, updatedAt, clicks).
`POST`	`/api/configs`	Создание: `{ name, settings }`, где `settings` соответствует схеме `SocialFloatingConfig`. Возвращает `{ id, version }`.
`GET`	`/api/configs/:id`	Полный объект конфига.
`PUT`	`/api/configs/:id`	Обновление имени или настроек.
`POST`	`/api/configs/:id/publish`	Увеличивает версию, переводит статус в `published`.
`GET`	`/api/configs/:id/events`	Последние события (если стор поддерживает хранение, например `file`).

Схема SocialFloatingConfig описана в services/social-floating/src/schemas/config.ts: позиция (left|right), форма (rounded|circle|pill), анимация (slide|bounce|pulse), массив кнопок (до 10 элементов), responsive-правила, триггеры показа (showAfterSeconds, showOnScrollPercent) и т.д.

Пример полезной нагрузки для создания:

{
  "name": "Telegram + WhatsApp",
  "settings": {
    "position": "right",
    "shape": "rounded",
    "animation": "slide",
    "showLabel": true,
    "shadow": true,
    "spacing": 12,
    "offsetX": 18,
    "offsetY": 60,
    "clickTracking": true,
    "responsive": { "hideOnMobile": false },
    "displayRules": { "showAfterSeconds": 2 },
    "buttons": [
      { "id": "tg", "label": "Telegram", "url": "https://t.me/example", "bgColor": "#2AABEE", "textColor": "#fff", "emoji": "✈️" },
      { "id": "wa", "label": "WhatsApp", "url": "https://wa.me/79991112233", "bgColor": "#25D366", "textColor": "#fff", "emoji": "💬" }
    ]
  }
}

3. Публичные эндпоинты (embed)

Метод	Путь	Назначение
`GET`	`/embed/health`	Проверка готовности (без кеша).
`GET`	`/cfg/:id.json`	JSON выбранной конфигурации, кешируется 5 минут.
`GET`	`/embed/:id.js`	Генерируемый JavaScript, готовый к вставке (см. ниже).

Basic сниппет

<!-- Social Floating -->
<script src="https://word-pres.ru/api/v1/social-floating/embed/CONFIG_ID.js" async defer></script>

CONFIG_ID — значение id из админки/API.
Скрипт автоматически подключает стили, рендерит блок, отслеживает клики, учитывает responsive и displayRules.
Чтобы загрузить JSON напрямую, используйте https://word-pres.ru/api/v1/social-floating/cfg/CONFIG_ID.json.

На локали меняем домен на http://127.0.0.1:3500.

Настройка отслеживания

Поля clickTracking и displayRules управляют поведением:

clickTracking=true → embed вызывает POST /events с event=click, meta.buttonId.
displayRules.showAfterSeconds (число) → задержка появления.
displayRules.showOnScrollPercent → показать после прокрутки заданного процента страницы.

4. События

POST /events принимает одиночный объект или массив:

{
  "id": "abc123def",
  "event": "click",      // click | view | custom
  "t": 1732260000000,
  "meta": { "buttonId": "tg" }
}

Без авторизации.
Хранение доступно, если адаптер поддерживает (file store сохраняет последние 200 событий на конфиг).
Ответ: { "stored": <количество сохранённых событий> }.

5. HTML-админка

GET /admin демонстрирует базовый кабинет:

Список конфигов с поиском.
Копия сниппета и ссылки на JSON.
Таблица последних событий.

Эту страницу удобно использовать как fallback, пока основная SPA не готова. Можно открыть через gateway (/api/v1/social-floating/admin).

6. Хранение и резервное копирование

memory — только для разработки; данные пропадут при перезапуске.
file — JSON с configs и events. Путь задаётся SOC_FILE_PATH. Файл обновляется атомарно через *.tmp + rename. Добавьте его в бэкапы.
При необходимости можно реализовать адаптер для SQLite/PostgreSQL (реализуйте интерфейс StoreAdapter).

7. Проверка после вставки

Откройте сайт с внедрённым скриптом.

В DevTools → Console:

typeof window.SocialFloatingRoot; // undefined — норма, компонент полностью инкапсулирован

Проверьте наличие блока .sf-floating-root в DOM и кликабельность кнопок.
Убедитесь, что POST /events отвечает stored > 0 (Network → XHR/fetch).

8. Типовые ошибки и решения

Симптом	Причина	Решение
404 на `/embed/CONFIG.js`	Gateway не достучался до сервиса	Проверьте, что `pnpm --filter @saas-apps/service-social-floating dev` запущен и `SOCIAL_FLOATING_URL` указывает на него.
Кнопки не появляются	Пустой массив `buttons` или триггеры (`showAfterSeconds`, `showOnScrollPercent`) ещё не сработали	Заполните кнопки в конфиге и дождитесь условий показа.
События не пишутся	Используется memory-store без `appendEvent`	Переключитесь на `file` (или кастомный стор) либо реализуйте события в memory-режиме.
Нужен другой домен в сниппете	`GATEWAY_URL` не совпадает с прод-доменом	Укажите `GATEWAY_URL=https://word-pres.ru` в env и перезапустите сервис.

Вопросы и доработки фиксируйте в docs/app-platform-bootstrap.md или напрямую в README сервиса.