AACSearch / guide
Storefront UI (aacsearch-ui)
Search page, autocomplete, ⌘K palette, support chat, voice, photo search and recommendations — in React or on any HTML page.
aacsearch-ui is the platform's UI package: React InstantSearch widgets over
the tenant API, an assistant-ui chat wired to the assistants API, shadcn/ui
components, and a framework-free bundle for sites without React. Everything
speaks to the API through the generated TypeScript SDK with one search key
and one session id, so events, recommendations and the assistant all see the
same visitor.
React
import { AACSearchExperience, AACSupportChat, defineAACSearchConfig } from "aacsearch-ui/experience";
const config = defineAACSearchConfig({
apiUrl: "https://api.aacsearch.com/v1",
apiKey: NEXT_PUBLIC_SEARCH_KEY, // a search key — never a full one
collection: "products",
queryBy: "name,brand,description",
locale: "ru",
currency: "RUB",
facets: [{ attribute: "category.lvl0", type: "hierarchical" }, { attribute: "brand" }, { attribute: "price", type: "range" }],
recommendations: { trending: "trending", similar: "similar", personal: "for-you" },
semantic: { vectorField: "embedding" },
image: { vectorField: "image_embedding" },
voice: { language: "ru" },
assistant: { assistantId: "asst_…" },
});
export default function Page() {
return (
<>
<AACSearchExperience config={config} />
<AACSupportChat config={config} />
</>
);
}Add @import "aacsearch-ui/globals.css"; and @source "../node_modules/aacsearch-ui/src";
to the app's Tailwind 4 stylesheet once.
Any site
<script type="module" src="https://cdn.aacsearch.com/aacsearch-ui.js"></script>
<aacsearch-app api-url="https://api.aacsearch.com/v1" api-key="SEARCH_KEY" collection="products"
query-by="name,brand" facets="brand,category" price-field="price" lang="ru" currency="RUB"
trending-model="trending" similar-model="similar" voice vector-field="image_embedding"
assistant-id="asst_…"></aacsearch-app>
<aacsearch-chat api-url="…" api-key="SEARCH_KEY" collection="products" assistant-id="asst_…"></aacsearch-chat>
<aacsearch-recommendations api-url="…" api-key="SEARCH_KEY" collection="products" kind="recently-viewed"></aacsearch-recommendations>From the cart and checkout pages, report what closes the loop:
window.AACSearchUI.track(config, { type: "purchase", value: 12990, currency: "RUB", objects: [{ id: "42", price: 12990, quantity: 1 }] });The lighter aac-search.js (autocomplete, search page, recommendations, no
React) exposes the same AACSearch.mount* and AACSearch.track API.
What the search key pays for
The assistant, voice input, photo search and the semantic fallback are AI operations: they are charged to your organization's credits and limited per visitor session — see keys, scopes and credits. When the wallet runs out the widgets degrade rather than break: search keeps working, the assistant reports it is unavailable.
Languages
Every visitor-facing string comes from the package's dictionaries (ru and
en built in; pass messages for another language or to override labels). The
locale drives number and currency formatting, the assistant's suggestion chips
and the voice recogniser's language.