Правила аналитики и метрики

Под тегом analytics скрываются две независимые системы. Метрики вычисляются по требованию из тех же событий, которые витрина уже отправляет в POST /events (см. события и рекомендации), — настраивать ничего не нужно, если события уже несут found, doc_ids и value. Правила аналитики — отдельный движок именованных счётчиков, который вы настраиваете явно для того, что не покрывают метрики: например, виджет «популярные запросы» на основе собственной коллекции или журнал сырых событий по одному свойству.

Каждой операции на этой странице нужен полный ключ (см. ключи и области доступа). Ни одна из них не запускает модель, и ни одна не оплачивается кредитами.

Метрики качества поиска

Четыре эндпоинта только для чтения агрегируют сохранённые поисковые события за период. Каждому нужен ограниченный диапазон from/to (ISO 8601, не больше 366 дней), и каждый принимает необязательный фильтр collection:

const queries = await client.analytics.listAnalyticsQueryMetrics({
  from: "2026-08-01",
  to: "2026-08-31",
  collection: "products",
  limit: 50,
});
// queries.data[0] -> { q, searches, results_found_rate, clicks, ctr, no_click_rate, add_to_carts, purchases, revenue, conversion_rate, revenue_per_search }

curl -G https://api.aacsearch.com/v1/analytics/metrics/zero-results \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  --data-urlencode "from=2026-08-01" --data-urlencode "to=2026-08-31"

Ответы queries / zero-results / revenue-attribution постранично отдаются через limit/offset и несут next_offset (null, когда прочитаны все строки) и total — количество до пагинации. events показывает, сколько сырых событий запрос обошёл, чтобы построить страницу; truncated: true значит, что диапазон содержал больше событий, чем сервер обходит за один запрос, и цифры относятся только к самым ранним строкам — в этом случае сузьте диапазон, а не доверяйте усечённому итогу. Доля нулевых результатов взвешена по поискам (1 - results_found_rate), а не по запросам, поэтому несколько популярных беррезультатных запросов сдвигают её сильнее, чем много редких.

Готового виджета для этих метрик нет — на них строятся экраны аналитики консоли; вызывайте их напрямую для собственной панели.

Правила аналитики

Правило аналитики называет счётчик или журнал, который наполняет createAnalyticsEvent, — независимо от конвейера событий выше:

У правила есть type, отслеживаемые collection и event_type, и объект params, чья форма зависит от type:

await client.analytics.createAnalyticsRule({
  name: "products-popular-queries",
  type: "popular_queries",
  collection: "products",
  event_type: "search",
  params: { destination_collection: "products_popular_queries", limit: 1000 },
});

Отправка и чтение событий правила

createAnalyticsEvent — POST /analytics/events — записывает одно событие для названного правила:

await client.analytics.createAnalyticsEvent({
  name: "products-popular-queries",
  event_type: "search",
  data: { user_id: "u_42", q: "аккумуляторная дрель", filter_by: "in_stock:true" },
});

getAnalyticsEvents — GET /analytics/events — читает последние события одного user_id по правилу name (до n, максимум 1000):

const recent = await client.analytics.getAnalyticsEvents({ user_id: "u_42", name: "products-popular-queries", n: 20 });

Удаление правила (deleteAnalyticsRule) останавливает агрегацию новых событий; оно не удаляет destination_collection правила и уже записанные в неё документы.