Коннекторы и виджет — обзор
Как CMS-коннекторы и встраиваемый виджет передают данные в AACsearch и показывают результаты поиска в вашем магазине.
AACsearch подключается к вашей CMS через две независимые поверхности:
- Connector API — набор HTTP-эндпоинтов, которые модуль вашей CMS вызывает для отправки данных о товарах в AACsearch. Модуль работает на вашем сервере; AACsearch не опрашивает ваш магазин самостоятельно.
- Встраиваемый виджет — Vanilla JS бандл, который AACsearch отдаёт по адресу
/api/widget/widget.js. Вы вставляете один тег<script>в шаблон магазина — виджет берёт на себя интерфейс поиска, фильтры, сортировку и трекинг кликов.
Эти две поверхности используют разные типы токенов и никогда не передают административные ключи AACsearch.
CMS-модули обязаны вызывать только эндпоинты Connector API, описанные в Жизненный цикл Connector API. Модулям запрещено писать напрямую во внутренние хранилища AACsearch (Typesense, SearchIngestBuffer, административный ключ поиска). Прямые записи обходят изоляцию арендатора, контроль квот и буфер ингеста — это ломает систему незаметным способом.
Модель токена коннектора
Токены коннектора используют префикс ss_connector_* и хранятся как строки SearchApiKey с областью действия connector_write. Они создаются в панели AACsearch и привязываются к конкретному поисковому индексу.
Свойства токена:
- Префикс:
ss_connector_ - Область действия:
connector_write - Хранится как: SHA-256 хеш (формат
prefix:hash) в полеSearchApiKey.hash - Plaintext возвращается ровно один раз при создании — никогда повторно
- Можно отозвать в любой момент из панели
Создайте токен через Панель → Connectors → Новый токен коннектора или вызовом oRPC-процедуры search.createConnectorToken.
Матрица поддержки платформ
Жизненный цикл каждой интеграции:
- Supported — модуль выпускается с каждым релизом, проверен на боевых магазинах, обратная совместимость сохраняется.
- Beta — модуль выпускается и работоспособен, но есть известные пробелы в маппинге, обработке ошибок или плановой синхронизации. Подходит для staging и пилотов.
- Early preview — каркас модуля лежит в монорепозитории, функционал собран и пригоден к ручной установке, но скачиваемый пакет ещё не опубликован.
- Planned — дизайн зафиксирован в
wiki/tasks/cms-platform-expansion.md; модуль не начат. - Integration guide — плагин не нужен; AACsearch подключается через нативный webhook/event API платформы и описан как конфигурационный рецепт.
| Платформа | Статус | Путь модуля / пакета | Документация |
|---|---|---|---|
| PrestaShop 8.x | Early preview | modules/prestashop/aacsearch/ | PrestaShop |
| 1C-Bitrix (self-hosted) | Early preview | modules/bitrix/aac.search/ | Bitrix |
| WordPress (без Woo) | Early preview | modules/wordpress/aacsearch-search/ | WordPress / WooCommerce |
| WooCommerce | Planned | — | WordPress / WooCommerce |
| Shopify | Early preview | packages/shopify-connector/ | Shopify |
| Strapi 5.x | Beta | packages/strapi-plugin/ | Strapi |
| Contentful | Integration guide | webhook-based | Contentful |
| Sanity.io | Integration guide | GROQ + listener | Sanity |
| Direct API | Supported | — | Custom Connector |
| OpenCart 3.x / 4.x | Planned | — | — |
| Magento 2 | Planned | — | — |
| Drupal / Joomla | Planned | — | — |
| InSales | Planned | — | — |
| Directus / Payload CMS | Planned | — | Headless CMS |
| Supabase / Postgres | Integration guide | packages/supabase-sync/, packages/postgres-sync/ | Supabase Sync, Postgres Sync |
| Zapier | Integration guide | — | Zapier |
Детальный план реализации каждой Planned-платформы (структура файлов, эндпоинты, сигнатуры мапперов) хранится в wiki/tasks/cms-platform-expansion.md. Если вашей платформы нет в списке вообще — собирайте интеграцию по Custom Connector напрямую через Connector API.
С чего начать
- Создайте поисковый индекс — Панель → Search → Indexes → Новый индекс.
- Создайте токен коннектора — Панель → Connectors → Новый токен. Сразу скопируйте plaintext-значение.
- Установите модуль CMS — загрузите модуль PrestaShop, Bitrix или WordPress в магазин, либо реализуйте свою интеграцию через Connector API.
- Запустите handshake — модуль вызывает
POST /api/connectors/handshakeс вашим токеном. Успешный ответ подтверждает валидность токена и возвращает slug индекса. - Запустите полную синхронизацию — модуль экспортирует все товары и шлёт их пачками в
POST /api/projects/:projectId/sync/full. Товары попадают вSearchIngestBufferи индексируются асинхронно. - Встройте виджет — скопируйте сниппет из Search → Widget и вставьте в шаблон магазина.
Принцип архитектуры
Модули CMS и браузеры никогда не обращаются к хранилищу AACsearch напрямую. Все данные проходят через API-слой AACsearch, который валидирует, проверяет авторизацию, применяет квоты и складывает записи в SearchIngestBuffer. Административный поисковый ключ никогда не покидает сервер AACsearch.
CMS-модуль (bearer: ss_connector_*)
│
▼
Connector API ← валидация токена, проверка scope
│
▼
SearchIngestBuffer (Prisma DB)
│
▼
Фоновый воркер → AACsearch (Typesense)Эта граница неприкосновенна. Connector API — единственный поддерживаемый путь записи данных CMS. См. Архитектура поиска для полного жизненного цикла ингеста и правил изоляции арендаторов.
Связанные страницы
- Жизненный цикл Connector API — все 7 эндпоинтов, форматы запросов, коды ошибок
- Диагностика — тест соединения, отчёт об ошибках, поведение при повторных попытках
- Custom Connector — руководство разработчика по созданию нового коннектора
- PrestaShop
- Bitrix
- Shopify
- WordPress / WooCommerce
- Headless CMS — Strapi, Sanity, Contentful, Directus, Payload
- Обзор виджета
- События аналитики виджета