#Модули для сайтов

Статус: Доступно — Bitrix sapport.connector 1.2.1 и WordPress sapport-connector-wp 1.1.1. Бета — FastAPI sapport-connector 1.0.0 и Nuxt @sapport/nuxt-connector 1.0.0: пакеты готовы, но в кабинете помечены «скоро» (не опубликованы).

Назначение: подключить сайт на CMS или фреймворке к Формула ИИ одним модулем: счётчик посещений, серверный маячок (виден роботам и ИИ-краулерам), чат, сбор поведения и публикация статей из Формула ИИ.

#Содержание

1. Когда использовать
2. Общее для всех модулей
3. Bitrix
4. WordPress
5. FastAPI
6. Nuxt
7. Протокол коннектора для собственных модулей
8. Открытые вопросы

#Когда использовать

#Общее для всех модулей

#Доступ

#Что делает модуль

#Как привязать сайт: код привязки

1. В кабинете: «Продвижение → Система → Сайты (модуль)» → добавьте домен → получите код привязки.
2. Код имеет префикс ячейки: RU-…, EN-… или ID-…. Он живёт 15 минут и одноразовый. Код чужой ячейки даёт ошибку «код не найден».
3. Введите код в модуле. Модуль обменивает его на site_id, публичный ключ, секрет и ключ маячка (секрет отдаётся один раз).
4. Если код истёк или использован, нажмите «Новый код». «Отключить» отвязывает сайт на стороне облака.

Состояния сайта в кабинете: pending (код выдан, привязки нет), bound (привязан), disabled (выключен).

Привязка допускает только зарегистрированный домен. Алиас домена или другой хост даёт ошибку domain_mismatch (при привязке) или 400 (на серверном маячке); www. поддерживается, если модуль его учитывает.

#Скачивание

Архивы и контрольные суммы SHA-256 — в кабинете: «Настройки → Интеграции → Модули для сайтов». Сверяйте сумму перед установкой.

Файлы берутся с домена своей ячейки (RU https://formula-cream.pro, EN https://wfacademy.org, ID https://wfacademy.id).

#Режимы серверного маячка

#Bitrix: sapport.connector 1.2.1

Статус: Доступно.

#Требования

#Установка

1. Распакуйте архив в /local/modules/.
2. В административной части откройте «Marketplace → Установленные решения» (/bitrix/admin/partner_modules.php) и нажмите «Установить» у «Sapport: коннектор».
3. Получите в кабинете Формула ИИ код привязки (см. выше).
4. «Настройки → Настройки продукта → Настройки модулей → Sapport: коннектор» → введите код → «Привязать».
5. Нажмите «Проверить связь».

Рекомендации:

• Включите агенты Bitrix на cron (иначе heartbeat и публикатор запаздывают).
• Если сайт работает за прокси и передаёт X-Forwarded-For, отметьте «Сайт работает за прокси» — иначе IP посетителя заменится адресом прокси.

#Что делает модуль

#Настройки

Включённость частей (tracker, behaviour, chat, режим согласия, режим маячка) задаётся в кабинете.

#Проверка

1. Кнопка «Проверить связь» → успех.
2. В кабинете состояние сайта — bound.
3. После визита с обычного браузера в «Обзоре» растёт счётчик; бот-хит можно проверить curl -A "Googlebot" https://ваш-сайт/.
4. Страница отдаёт тег loader.js?k=… в <head>.

#Обновление и удаление

• Обновление: замените содержимое папки модуля новой версией; перепривязка не нужна. Если облако ответит update_required (unknown_kid или kid_wrong_cell), обновите модуль: он не знает ключ подписи заданий.
• Удаление: Marketplace → «Удалить». Отвяжите сайт заранее («Отключить» в кабинете), иначе привязка останется на стороне облака.

#Частые проблемы

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

Секрет привязки хранится в таблице b_option в открытом виде, поэтому резервные копии базы содержат его. Перевыпуск секрета — только отвязкой и новой привязкой.

#WordPress: sapport-connector-wp 1.1.1

Статус: Доступно.

#Требования

#Установка

1. «Плагины → Добавить новый → Загрузить плагин», выберите zip, нажмите «Установить» и «Активировать».
2. «Настройки → Формула ИИ».
3. Вставьте код привязки → «Подключить».
4. Нажмите «Проверить связь».

#Что делает плагин

#Особенности

#Проверка, обновление, удаление

• Проверка: «Проверить связь» → успех; в кабинете состояние bound; в <head> присутствует loader.js?k=….
• Обновление: загрузите новый zip поверх (автообновления нет).
• Удаление: сначала «Отключить» в кабинете, затем деактивируйте и удалите плагин.

#Частые проблемы

#FastAPI: sapport-connector 1.0.0 (Бета)

Статус: Бета. Пакет собран и описан, но в кабинете помечен «скоро / Пакет готовится»; файлов на странице скачивания пока нет.

#Требования

Python 3.11 и новее, PostgreSQL (та же база, где лежат статьи сайта), исходящий HTTPS к домену ячейки. Модуль не открывает входящих адресов для облака.

#Установка и привязка

# 1. Проверьте контрольную сумму файла из кабинета
sha256sum sapport_connector-1.0.0-py3-none-any.whl

# 2. Установите
pip install "./sapport_connector-1.0.0-py3-none-any.whl[postgres]"

# 3. Создайте таблицы модуля
sapport-connector migrate

# 4. Привяжите домен кодом из кабинета
SAPPORT_SITE__RU_MAIN__HOST=example.ru \
sapport-connector bind --site ru_main --code RU-XXXXXXXXXX \
  --secret-file /run/secrets/sapport_ru_main --env-file /etc/sapport/sapport.env

# 5. Самопроверка: все строки [OK]
sapport-connector selftest

# 6. Запустите worker (systemd/supervisor) или cron: sapport-connector run-once
sapport-connector worker

Команды CLI: bind, migrate, selftest, run-once, status, worker, unbind (необратима). Имя на PyPI занято заглушкой — ставьте только архив из кабинета.

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

Секрет записывается в файл, а не в переменную окружения. Полный перечень и контракт адаптера статей — в документации пакета (README, INTEGRATION, ADAPTER, PROTOCOL, ERRORS, ACCEPTANCE, SECURITY, CSP, OPERATIONS, COMPATIBILITY, TROUBLESHOOTING).

#Что нужно написать вам

Публикатор требует адаптер под вашу таблицу статей (контракт — ADAPTER), а обложки — класс медиахранилища на общем для реплик хранилище. Без медиахранилища статьи публикуются без обложки. Пока публикатор выключен, модуль только поддерживает связь и heartbeat.

#Проверка

sapport-connector status и selftest; в кабинете сайт bound. Для подробной диагностики веб-процесса подключите healthz_router() и закройте адрес на обратном прокси.

#Nuxt: @sapport/nuxt-connector 1.0.0 (Бета)

Статус: Бета. Пакет не опубликован.

Nuxt-часть работает вместе с Python-worker: привязывает сайт worker, а Nuxt получает только производный ключ маячка. Им нельзя забрать задания или отвязать сайт.

#Требования

Nuxt 3.13+ или 4.x в режиме Node-сервера (Nitro 2, Node 18.17+; для Nuxt 4 — Node 20+). Nuxt 5 не поддерживается.

#Установка

sha256sum sapport-nuxt-connector-1.0.0.tgz
npm install ./sapport-nuxt-connector-1.0.0.tgz

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@sapport/nuxt-connector'],
  sapport: {
    exclude: ['/admin'],
    trustedProxies: ['127.0.0.1'],
  },
});

Ключ не пишется в nuxt.config. Переменные окружения сервера Nuxt:

SAPPORT_SITES=ru_main
SAPPORT_SITE__RU_MAIN__HOST=example.ru
SAPPORT_SITE__RU_MAIN__CELL=ru
SAPPORT_SITE__RU_MAIN__ID=<site_id>
SAPPORT_SITE__RU_MAIN__BEACON_KEY_FILE=/run/secrets/beacon/sapport_ru_main.beacon
NUXT_SAPPORT_DIAGNOSTICS_TOKEN=<случайная строка не короче 16 знаков>

Worker и Nuxt запускайте под разными пользователями ОС: файл корневого секрета не должен читаться процессом Nuxt.

#Использование в страницах

<script setup lang="ts">
useSapportPage({ type: 'article', id: article.id });
const consent = useSapportConsent();
</script>
<template>
  <button @click="consent.grant()">Принять</button>
  <button @click="consent.deny()">Отклонить</button>
</template>

#Диагностика

curl -s -H "Authorization: Bearer $NUXT_SAPPORT_DIAGNOSTICS_TOKEN" https://ваш-сайт/_sapport/health

Ожидается "ok": true, у привязки config.state: "valid", после первого просмотра beacon.sent ≥ 1.

#Ограничения

#Протокол коннектора для собственных модулей

Статус: Доступно для модулей, которые вы пишете сами. Протокол используют четыре готовых модуля; его перечень может расширяться совместимо.

Адрес: https://<домен ячейки>/api/v1/connector/…. Все запросы, кроме bind, подписываются HMAC.

#Подпись запроса

Заголовки:

Строка подписи (пять строк через \n):

<ts>
<nonce>
<METHOD>
<path без query-строки>
<sha256hex(тело запроса)>

• Допустимое расхождение времени — ±300 секунд.
• Nonce хранится 600 секунд; повтор даёт 401. Если хранилище nonce недоступно, ответ 503.
• Ключ HMAC — корневой секрет привязки. Для track/visit и beacon-config допустим производный ключ маячка:

beacon_key = hex(HMAC-SHA256(secret, "sapport-beacon-v1:" + site_id))

Тестовые векторы подписи и заданий лежат в поставке модулей (tests/_vectors/, файлы signing-vectors.json, job-vectors.json). Не копируйте секреты из примеров документации в рабочие системы.

#Методы

#bind

POST /api/v1/connector/bind
Content-Type: application/json

{
  "code": "RU-XXXXXXXXXX",
  "site_url": "https://example.ru",
  "cms": "fastapi_nuxt",
  "module_version": "1.0.0"
}

Ответ 200:

{
  "site_id": "00000000-0000-4000-8000-000000000000",
  "public_key": "0123456789abcdef0123456789abcdef",
  "secret": "EXAMPLE_SECRET_SHOWN_ONCE",
  "beacon_key": "0000000000000000000000000000000000000000000000000000000000000000",
  "api_base": "https://formula-cream.pro/api/v1",
  "loader_url": "https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef",
  "config": { "tracker": true, "behaviour": false, "chat": false, "consent_mode": "wait", "server_beacon": "full" },
  "disabled": false
}

secret возвращается один раз. Ошибки: 400/413 bad_request, 404 code_not_found (код неизвестен, истёк, использован или принадлежит другой ячейке), 409 domain_mismatch, 429 rate_limited, 500 internal.

#heartbeat

Ответ 200: { "config": {…}, "min_module_version": "1.2.1", "disabled": false, "pending_jobs": 0 }. Ответ 403 с { "disabled": true } означает, что сайт выключен.

#beacon-config

{
  "tracker": true,
  "server_beacon": "full",
  "disabled": false,
  "consent_mode": "wait",
  "loader_url": "https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef",
  "public_key": "0123456789abcdef0123456789abcdef",
  "ttl_seconds": 3600
}

Кэшируйте снимок на ttl_seconds.

#track/visit (серверный хит)

Поля тела описаны на странице JS/PHP-трекер. Особенности подписанного вызова:

• Хост хита берётся из реестра привязок. Если он не совпадает с зарегистрированным доменом, ответ 400.
• Режим server_beacon=off, выключенный tracker или отсутствие доступа арендатора дают 403.
• Режим anonymous обнуляет хеши IP и User-Agent, образец UA и страну.
• Дневная квота токена даёт 204 без записи.

#jobs и result

Задания подписываются Ed25519 (поле kid с префиксом ячейки ru-/en-/id-, канонический JSON с сортировкой ключей в порядке UTF-16). Ответ на GET /jobs не идемпотентен: выданное, но не подтверждённое задание выдаётся повторно через 15 минут. Ошибка 503 signing_unavailable означает временную недоступность подписи заданий.

result принимает статус applied, skipped, conflict, failed. Первый присланный итог окончателен.

Пределы статьи едины для облака и модулей: HTML не более 2 000 000 байт, полезная нагрузка задания не более 3 000 000 байт. Подробнее — Статьи.

#Рекомендации для собственного модуля

• Подписывайте тело ровно теми байтами, что отправляете.
• Считайте серверный хит статистикой: не повторяйте при ошибке, не блокируйте ответ страницы (разумный таймаут — 150–200 мс).
• Не отдавайте корневой секрет фронтенду: для маячка достаточно производного ключа.

#Открытые вопросы

1. Техническое. FastAPI и Nuxt: реальное наличие файлов в каталоге раздачи не проверялось; в кабинете модуль помечен «скоро». До публикации пакетов страницы остаются Бета.
2. Техническое. Модуль Bitrix, режим anonymous: WordPress обнуляет query-строку на своей стороне, а облако в режиме full читает UTM из query. Нужно решить единое правило для всех модулей.
3. К владельцу. Значение cms для собственных модулей: допустимы только bitrix, wordpress, fastapi_nuxt. Как регистрировать модуль на другой платформе, не определено.
4. Техническое. Путь к настройкам в Bitrix: README модуля называет раздел кабинета «подключение сайтов» без пути; здесь использован путь из интерфейса «Продвижение → Система → Сайты (модуль)».