Виджет

Виджет — это набор пользовательских элементов (custom elements), которые раздаются с CDN. Достаточно тега script и элемента на странице — без сборки и фреймворка, а новая версия попадает на ваш сайт без повторного деплоя с вашей стороны. Для приложения на React используйте пакет aacsearch-ui.

Главное правило: поисковый ключ и только наш API

Браузер обращается только к API (https://api.aacsearch.com/v1) и только с ключом области search:

• Поисковый ключ умеет искать, получать рекомендации, отправлять события и вызывать AI-операции для посетителей. Он не может записывать документы или читать настройки — на всё остальное API отвечает 403, поэтому худшее, что можно сделать скопированным со страницы ключом, — это искать. Полный список — в разделе ключи и области доступа.
• Полный ключ никогда не размещается на странице: он дал бы любому посетителю право изменить или удалить ваш каталог.
• Браузер никогда не обращается к поисковому движку напрямую. Изоляцию организаций, ограничения ключа, квоты, поисковые правила и аналитику применяет API, и запрос в обход него обходит их все.

Получить поисковый ключ можно двумя способами:

const { key, expires_at } = await client.browserKeys.createBrowserKey({
  expires_in_seconds: 86400,
  allowed_collections: ["products"],
  allowed_origins: ["https://shop.example.com"],
});
// подставьте `key` в страницу как api-key виджета

Отзыв или ротация родительского полного ключа делает недействительными все выпущенные из него браузерные ключи.

Поиск: aac-search.js

Лёгкий виджет — автодополнение и полноценная страница результатов в одном элементе. Он рендерится в shadow root, поэтому CSS магазина не может его перекрасить.

<script type="module" src="https://cdn.aacsearch.com/aac-search.js"></script>

<aac-search
  api-url="https://api.aacsearch.com/v1"
  api-key="SEARCH_KEY"
  collection="products"
  query-by="name,brand"
  facet-by="brand,category"
  fields='{"title":"name","subtitle":"brand","price":"price","url":"url","image":"image"}'
  locale="ru"
  currency="RUB"
></aac-search>

Если обязательного атрибута нет, виджет выводит его название на странице вместо молчаливой ошибки.

Блок рекомендаций из того же бандла:

<aacsearch-recommendations
  api-url="https://api.aacsearch.com/v1"
  api-key="SEARCH_KEY"
  collection="products"
  model-id="similar"
  object-id="42"
  k="6"
  title="Похожие товары"
></aacsearch-recommendations>

model-id обязателен; object-ids (корзина), exclude-ids, filter-by, fields, locale и currency — необязательны. Старый тег <nova-recommendations> продолжает работать.

Оформление

Оформляйте виджет CSS-переменными на самом элементе или любом его предке — только они проходят через границу shadow DOM:

aac-search {
  --nova-accent: #0f766e;
  --nova-radius: 12px;
  --nova-font: "Inter", system-ui, sans-serif;
}

Также доступны: --nova-surface, --nova-text, --nova-border, --nova-hover, --nova-mark.

Поиск с AI-ассистентом: aacsearch-ui.js

Подключайте на страницу только один бандл: оба регистрируют <aacsearch-recommendations>, и тег достаётся тому, кто загрузился первым.

Полный набор — страница поиска, AI-ассистент, чат поддержки и рекомендации — в виде пользовательских элементов. Стили подгружаются автоматически по адресу самого скрипта (переопределяется атрибутом styles-url).

<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"
  assistant-id="asst_…"
></aacsearch-app>

<aacsearch-chat
  api-url="https://api.aacsearch.com/v1"
  api-key="SEARCH_KEY"
  collection="products"
  query-by="name,brand"
  assistant-id="asst_…"
></aacsearch-chat>

<aacsearch-recommendations
  api-url="https://api.aacsearch.com/v1"
  api-key="SEARCH_KEY"
  collection="products"
  query-by="name"
  kind="trending"
></aacsearch-recommendations>

Всем трём элементам нужны api-url, api-key, collection и query-by; <aacsearch-chat> дополнительно требует assistant-id (ассистент создаётся в консоли). Вместо отдельных атрибутов всю конфигурацию можно передать JSON-ом в config="{…}".

Сообщайте о конверсиях со страниц корзины и оформления заказа, с теми же параметрами подключения, что и у элементов:

const config = { apiUrl: "https://api.aacsearch.com/v1", apiKey: "SEARCH_KEY", collection: "products", queryBy: "name,brand" };
window.AACSearchUI.track(config, { type: "purchase", value: 12990, currency: "RUB", objects: [{ id: "42", price: 12990, quantity: 1 }] });

Что отправляет виджет

• X-NOVA-API-KEY — поисковый ключ из атрибута api-key.
• X-NOVA-SESSION-ID — один идентификатор на вкладку браузера, создаётся автоматически. Он связывает поиски, клики и покупки посетителя для аналитики и A/B-тестов, и по нему считается лимит AI-операций на сессию.

Ассистент, голосовой ввод, поиск по фото и семантический резерв оплачиваются кредитами; когда баланс заканчивается, поиск продолжает работать, а ассистент сообщает, что недоступен. Подробнее — в разделе ключи, области доступа и кредиты.

Далее

• SEO-страницы — страницы, которые найдёт поисковый робот, рядом с поисковой строкой.
• Storefront UI — пакеты для React и чистого HTML.