Connectors & Widget Overview
How CMS connectors and the hosted widget push data into AACsearch and display search results in your storefront.
AACsearch connects to your existing CMS through two complementary surfaces:
- Connector API — a set of HTTP endpoints that CMS modules call to push product data into AACsearch. The module runs on your server; AACsearch never polls or scrapes your store.
- Hosted Widget — a Vanilla JS bundle served by AACsearch at
/api/widget/widget.js. You embed a single<script>tag in your storefront theme and the widget handles the search UI, facets, sorting, and click tracking.
Both surfaces use different token types. Neither surface ever exposes your AACsearch admin credentials.
CMS modules must call the Connector API endpoints documented in Connector API Lifecycle. Modules must never write directly to AACsearch search internals (Typesense, SearchIngestBuffer, or the admin search key). Direct writes bypass tenant isolation, quota enforcement, and the ingest buffer that absorbs upstream outages.
Connector token model
Connector tokens use the ss_connector_* prefix and are stored as SearchApiKey rows with the connector_write scope. They are created from the AACsearch dashboard and bound to a specific search index.
Token properties:
- Prefix:
ss_connector_ - Scope:
connector_write - Stored as: SHA-256 hash (prefix:hash format) in
SearchApiKey.hash - Plaintext returned once at creation — never again
- Revocable at any time from the dashboard
Create a connector token from Dashboard → Connectors → New Connector Token, or via the oRPC procedure search.createConnectorToken.
Platform support matrix
The lifecycle of each platform integration:
- Supported — a production module is shipped with each release. Field-tested. Backwards-compatible upgrades.
- Beta — module is shipped and functional but has known gaps in mapping, error handling, or scheduled sync. Suitable for staging or pilot stores.
- Early preview — module skeleton exists in the monorepo; feature-complete enough for manual install but not yet released as a downloadable package.
- Planned — design captured in
wiki/tasks/cms-platform-expansion.md; module not yet started. - Integration guide — no plugin needed; AACsearch is wired in via the platform's webhook/event API and documented as a configuration recipe.
| Platform | Status | Module path / package | Docs |
|---|---|---|---|
| PrestaShop 8.x | Early preview | modules/prestashop/aacsearch/ | PrestaShop |
| 1C-Bitrix (self-hosted) | Early preview | modules/bitrix/aac.search/ | Bitrix |
| WordPress (non-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 |
The detailed implementation plan for every Planned platform lives in wiki/tasks/cms-platform-expansion.md (file trees, API surface, mapper signatures). If your platform is missing entirely, build against the Custom Connector developer guide using the Connector API directly.
How to get started
- Create a search index — Dashboard → Search → Indexes → New Index
- Create a connector token — Dashboard → Connectors → New Connector Token. Copy the plaintext token immediately.
- Install the CMS module — upload the PrestaShop, Bitrix or WordPress module to your shop, or build your own integration using the Connector API directly.
- Run handshake — the module calls
POST /api/connectors/handshakewith your token. A successful response confirms the token is valid and returns the index slug. - Run full sync — the module exports all products and sends them in batches to
POST /api/projects/:projectId/sync/full. Products are queued to theSearchIngestBufferand indexed asynchronously. - Embed the widget — copy the install snippet from Dashboard → Search → Widget tab and paste it into your storefront theme.
Architecture principle
CMS modules and browsers never contact AACsearch storage directly. All data flows through the AACsearch API layer, which validates, auth-checks, rate-limits, and queues writes to the SearchIngestBuffer. The search admin key never leaves the server.
CMS module (bearer: ss_connector_*)
│
▼
Connector API ← validates token, checks scope
│
▼
SearchIngestBuffer (Prisma DB)
│
▼
Background worker → AACSearchThis boundary is invariant. The Connector API is the only supported write path for CMS data. See Search Architecture for the full ingest lifecycle and tenant isolation rules.
Related pages
- Connector API Lifecycle — all 7 endpoints, request shapes, error codes
- Diagnostics — test connection, error reporting, retry behavior
- Custom Connector — developer guide for building a new platform connector
- PrestaShop Module — install and configure the PrestaShop 8.x module
- Bitrix Module — install and configure the 1C-Bitrix module
- Shopify — Shopify connector preview
- WordPress / WooCommerce — WordPress module and WooCommerce status
- Headless CMS — Strapi, Sanity, Contentful, Directus, Payload
- Widget Overview — embed the hosted search widget
- Widget Analytics Events — event tracking reference