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

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

В этом разделе описаны custom events ассистента и tracking URL товарных подборок.

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

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

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 отсутствует или список товаров пустой, событие отправлять не нужно.

Поле	Назначение
`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`, если он есть на стороне клиента.

Пример 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.

Tracking товарных подборок

В ответе Shopping Assistant tracking-события могут находиться на двух уровнях:

Уровень	Где искать	Когда использовать
Рекомендательный блок	`events[]` в корне ответа	Для событий всего блока, например видимого показа `WRIMP`.
Товарная карточка	`response.contents[type="products"].value[].events[]`	Для `visible_impression` и `click` конкретного товара.

При наступлении события обработайте все элементы events[] с соответствующим type. Для каждого элемента выполните GET-запрос по каждому URL из urls[].

async function sendTrackingEvents(events, type) {
  const urls = events
    .filter((event) => event.type === type)
    .flatMap((event) => event.urls ?? (event.url ? [event.url] : []));

  await Promise.allSettled(
    urls.map((url) => fetch(url, { method: "GET", keepalive: true }))
  );
}

sendTrackingEvents(result.events ?? [], "WRIMP");
sendTrackingEvents(product.events ?? [], "visible_impression");

Отправляйте видимый показ один раз для одного фактического показа блока или карточки. Ошибка tracking-запроса не должна блокировать отображение рекомендаций или действие пользователя. Общие правила описаны в разделе Передача взаимодействий пользователя с кампаниями.

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

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

assistant_message_sent -> нет assistant_response_received

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

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