Справочник событий API

Все события принимает один эндпоинт:

POST {apiUrl}/api/v1/{projectId}/analytics/events
Content-Type: application/json

Ответ всегда 202 Accepted (приём асинхронный) или 422 при ошибке валидации. Лимит: 120 запросов в минуту с одного IP на проект. Актуальные JSON-схемы — в OpenAPI-спецификации платформы (/api/docs.json).

Общие поля

Поле	Тип	Описание
type	string	click | add_to_cart | purchase | contact | help_contact | goal. Поисковые запросы фиксируются сервером автоматически и этим эндпоинтом не принимаются — type: "search" вернёт 422
user_token	string, 36 симв.	Анонимный токен посетителя из localStorage — 36-символьный UUID, его создаёт виджет. Длина значима: события с токеном другой длины не попадают в отчёты качества (так отсекается служебный и автоматический трафик), а метрики этих отчётов покажут ноль. Если поле не передано, сервер построит псевдонимный токен из IP и User-Agent — он короче 36 символов, и такое событие в отчёты качества тоже не войдёт
query_id	uuid	queryID из ответа /search, к которому относится событие
from_search	bool	Атрибуция к поиску (окно 24 ч, проставляет виджет). Если не передан, выводится из analytics_tag: true только для product_clicked_after_search, для остальных тегов — false
attributed_query	string 2..255	Поисковый запрос, к которому атрибуцировано событие корзины/оплаты
source	string	Источник пути: query (набранный запрос), popular (выдача без запроса — популярные товары, превью), facets (выдача без запроса, собранная фильтрами). Проставляет виджет; атрибуцию не меняет — только помечает, как поиск участвовал в событии

Идентификаторы (object_id, order_id, object_ids) можно передавать строкой или числом — числовые id из фида приводятся к строке на приёме.

Суммы

Денежные поля называются amount и передаются в основных единицах валюты проекта (рубли, а не копейки) канонической decimal-строкой: "2599.00". Допустимо и число (2599), но строка надёжнее — она не зависит от того, как клиент печатает дробные числа.

Правило	Значение
Формат	только цифры и точка: ^\d{1,9}(\.\d{1,6})?$
Лишние знаки	округляются half-up до знаков валюты: "1000.555" → 1000.56
Валюта	настройка проекта; поле currency события — переопределение
Хранение	целые минорные единицы валюты события
Не принимается	"2 599,00", "2599,00", "2599 руб", отрицательные — 422

Поля revenue и price удалены

Прежний контракт принимал сумму в копейках (revenue). Оба поля больше не поддерживаются: запрос с ними получает 422 — молча записать 1/100 суммы хуже, чем отказать.

click

Поле	Обязательно	Описание
object_id	да	id товара или торгового предложения (offer id из фида) — торговое предложение сервис сам сведёт к товару
query	—	текст запроса, из выдачи которого кликнули
position	—	позиция карточки в выдаче, начиная с 1
analytics_tag	—	product_clicked_after_search — клик в выдаче; suggestion_selected — выбор подсказки; product_clicked — клик вне поиска

{ "type": "click", "object_id": "12345", "query": "iphone 15",
  "position": 2, "analytics_tag": "product_clicked_after_search",
  "query_id": "8475f51f-…", "user_token": "…" }

add_to_cart

Поле	Обязательно	Описание
object_id	да	id товара или торгового предложения — можно передавать id выбранного покупателем варианта
amount	—	цена позиции в основных единицах валюты (см. «Суммы»)
currency	—	ISO 4217, например RUB

{ "type": "add_to_cart", "object_id": "12345", "amount": "2599.00",
  "from_search": true, "attributed_query": "iphone 15", "user_token": "…" }

purchase

Поле	Обязательно	Описание
order_id	да	номер заказа. Покупки идемпотентны по order_id — повторная отправка не задваивает выручку
amount	—	сумма заказа в основных единицах валюты (см. «Суммы»). Без неё заказ учтётся как заказ, но выручка в панели не показывается вовсе — числа, которого не измеряли, там не будет
object_ids	—	id товаров или торговых предложений заказа (до 100) — участвуют в популярности товаров
currency	—	ISO 4217

{ "type": "purchase", "order_id": "A-10042", "amount": "2599.00",
  "currency": "RUB", "object_ids": ["12345", "67890"],
  "from_search": true, "attributed_query": "iphone 15", "user_token": "…" }

contact

След контакта с выдачей без набранного запроса — покупатель открыл окно поиска с популярными товарами или собрал каталог фильтрами. Виджет отправляет его сам (не чаще раза в 30 минут на поверхность); интеграторам передавать это событие не нужно. Оно не считается поисковым запросом и не тарифицируется.

{ "type": "contact", "source": "popular",
  "query_id": "…queryID ответа /search…", "user_token": "…" }

help_contact

Клик по контакту в блоке помощи при пустой выдаче: покупатель ничего не нашёл и пошёл звонить или писать. Виджет отправляет событие сам — блок и его контакты настраиваются в личном кабинете, на вкладке проекта «Виджет». Событие не считается поисковым запросом и не тарифицируется.

Поле	Тип	Описание
object_id	string	Обязательно. Вид контакта: phone, email, telegram, whatsapp, viber, max, vk, ok, link. Список закрыт — по нему считается разбивка отчёта
query	string 2..255	Запрос, на котором ничего не нашлось: по нему видно, какие поиски приводят покупателей к телефону

{ "type": "help_contact", "object_id": "whatsapp", "query": "красная сумка",
  "query_id": "…queryID пустого ответа /search…", "user_token": "…" }

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

goal

Конечное действие покупателя на сайтах без корзины — нажатие кнопки: «Узнать цену», «Заказать», «Запросить звонок». Заменяет корзину и заказ в отчётах, если у проекта включён режим «Цель конверсии» (Настройки → Настройки аналитики → раздел «Конверсия»). Приём события от режима не зависит — эндпоинт принимает goal всегда, для любого проекта.

Поле	Обязательно	Описание
object_id	—	id товара или торгового предложения, с которым связана цель — торговое предложение сервис сам сведёт к товару. Цель бывает и без товара, например форма-заявка
action	—	метка кнопки, на которой сработала цель, до 64 символов; лишние пробелы схлопываются. У проекта одна цель, а кнопок под неё может быть несколько — разрез отчёта «по действию» появляется, только когда значений action больше одного. Держите метку короткой и стабильной подписью кнопки («Узнать цену»), а не текстом про товар

{ "type": "goal", "object_id": "12345", "action": "Узнать цену",
  "from_search": true, "attributed_query": "iphone 15", "user_token": "…" }

У события goal нет своего analytics_tag — его место занимает action: поле analytics_tag в этом событии не принимается (422), и наоборот, поле action в событиях остальных типов тоже вернёт 422. Суммы, валюта и номер заказа (amount, currency, order_id) к цели не относятся и тоже вернут 422: воронка цели не денежная, и молча принятое поле выглядело бы записанным, хотя в отчётах его нет ни в одном числе.

У клика атрибуция к поиску может быть выведена из тега product_clicked_after_search. У цели такого тега нет: прямой интегратор обязан передавать from_search вместе с attributed_query сам — без них событие зачтётся как цель, но не попадёт в поисковую воронку.

Не отправляйте help_contact и goal с одной и той же кнопки: help_contact значит «покупатель не нашёл и пошёл звонить», goal — «нашёл и сделал целевое действие». Оба типа считаются отдельно и не суммируются — кнопка, отправляющая оба события, исказит сразу два отчёта.

Как события связаны с поиском

1. Каждый ответ POST /search содержит поле queryID (в multi-search — своё у каждого результата).
2. Виджет передаёт query_id из ответа /search в событии click — так клик привязывается к поиску, из которого он сделан.
3. Для корзины и оплаты виджет хранит последний поисковый контекст (query_id, запрос, время) и, если тот моложе 24 часов, проставляет from_search: true и attributed_query.
4. Запросы без текста (популярные товары, каталог по фильтрам) сервер не записывает как поиски, но окно атрибуции они открывают — след оставляет событие contact, а source на конверсиях говорит, каким был путь.