# Трекинг событий Shopping Assistant

Для анализа качества Shopping Assistant передавайте в Gravity Field custom events по ключевым шагам диалога. Эти события помогают понять, открывают ли пользователи чат, отправляют ли сообщения, получают ли ответы и где возникают ошибки или разрывы воронки.

В этом разделе описаны только custom events ассистента.

# Базовая воронка

Минимальная воронка диалога:

chat_dialog_open -> assistant_message_sent -> assistant_response_received

Если ответ содержит товарную подборку, дополнительно фиксируйте:

assistant_response_received -> assistant_product_selection_received

Ошибки и закрытия анализируются отдельно:

chat_error
chat_dialog_close
chat_dialog_end

# События ассистента

Событие	Когда отправлять
`chat_dialog_open`	Пользователь открыл чат ассистента.
`assistant_message_sent`	Пользователь отправил сообщение ассистенту.
`assistant_response_received`	Frontend получил и отобразил ответ ассистента.
`assistant_product_selection_received`	Ответ ассистента содержит товарную подборку.
`chat_error`	Frontend зафиксировал ошибку в сценарии ассистента.
`chat_dialog_close`	Пользователь закрыл чат.
`chat_dialog_end`	Диалог завершен.

# Как считать ответ полученным

Событие assistant_response_received отправляйте после того, как ответ успешно получен и добавлен в интерфейс чата. Если API ответил, но пользователь уже закрыл чат или frontend не смог отрендерить ответ, событие отправлять не нужно.

# Как считать товарную подборку

Событие assistant_product_selection_received отправляйте, если в ответе ассистента есть блок:

{
  "type": "products",
  "value": []
}

Если блок products отсутствует или список товаров пустой, событие отправлять не нужно.

# Рекомендуемые поля

Передавайте технические идентификаторы, которые позволяют связать события одного диалога и одного запроса. resourceId берите из user.uid Gravity Field. Его можно получить через POST /user.

Поле	Назначение
`threadId`	ID диалога. Должен совпадать с `threadId` в `/shopping/generate`.
`resourceId`	`uid` пользователя Gravity Field.
`messageId`	ID пользовательского сообщения, если клиентская сторона его генерирует.
`requestId`	ID запроса к ассистенту, если клиентская сторона его генерирует.
`trafficType`	`real` или `test`, если это значение используется в интеграции.
`tenant_id`	ID секции Gravity Field.
`campaignId`	ID кампании, если ассистент запущен из кампании.
`experienceId`	ID experience, если ассистент запущен из кампании.
`variationId`	ID variation, если ассистент запущен из кампании.
`latencyMs`	Время ожидания ответа, где применимо.
`errorCode`	Код ошибки для `chat_error`, если он есть на стороне клиента.

Не передавайте в event payload текст сообщений, персональные данные, чувствительные данные пользователя и другие данные, которые не нужны для аналитики воронки.

# Пример custom event

Ниже пример события для API V2. Дополнительные поля передаются в customProps.

{
  "type": "assistant_message_sent",
  "name": "Assistant Message Sent",
  "customProps": {
    "threadId": "thread-8f2b1c",
    "resourceId": "665f0a000000000000000001",
    "messageId": "message-1001",
    "requestId": "request-7001",
    "trafficType": "test",
    "tenant_id": "670ccaae56afcafaf808c146",
    "campaignId": "696a3dcf26ec5935e70a7f05",
    "experienceId": "69f9fd5a4006ae8b33086404",
    "variationId": "69f9fd5a4006ae8b3308640e"
  }
}

Для передачи события используйте тот же канал, который уже применяется в вашей интеграции: Web, API или SDK.

# Диагностика разрывов

Разрыв воронки возникает, когда пользователь отправил сообщение, но frontend не зафиксировал получение ответа:

assistant_message_sent -> нет assistant_response_received

Чтобы такие случаи можно было анализировать, важно:

использовать стабильный threadId на протяжении всего диалога;
передавать messageId или requestId для каждого пользовательского сообщения;
отправлять chat_error, если frontend получил ошибку;
отправлять chat_dialog_close, если пользователь закрыл чат;
передавать latencyMs в assistant_response_received и chat_error, если время ожидания известно.