События виджета Relavio Search

Виджет Relavio Search автоматически отправляет события кликов по товарам в API аналитики. Эти события связываются с поисковой сессией пользователя и помогают понять, какие запросы приводят к переходам на товары.

Какие события отправляет виджет

Сейчас виджет автоматически отправляет событие click при клике по карточке товара.

События отправляются из разных мест интерфейса:

• search - клик по товару в быстрых результатах поиска;
• suggests - клик по товару в блоке подсказок;
• catalog - клик по товару в каталожной сетке.

Источник сохраняется в metadata.list.

Endpoint событий

По умолчанию события отправляются POST-запросом в:

/api/v1/search/events

URL можно изменить параметром data-event-url или eventUrl.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-event-url="https://api.example.com/api/v1/search/events"
></div>

Заголовки запроса

Виджет отправляет события с такими заголовками:

Accept: application/json
Content-Type: application/json
api-key: YOUR_API_KEY

Если включен демонстрационный режим, дополнительно передается:

X-Relavio-Demo: demo-value

Запрос отправляется с credentials: include, поэтому браузер может передавать cookie поисковой сессии, если они установлены API.

Формат события клика

Пример события, которое отправляет виджет:

{
  "event_id": "click-1720000000000-abcd1234",
  "event_type": "click",
  "search_id": "search-id",
  "session_id": "session-id",
  "external_id": "product-123",
  "product_id": "123",
  "product_name": "iPhone 15",
  "position": 3,
  "page": 1,
  "price": 99990,
  "currency": "RUB",
  "metadata": {
    "list": "catalog",
    "url": "https://example.com/products/iphone-15"
  }
}

Обязательная часть события формируется всегда: event_id, event_type, search_id, session_id, external_id, product_name и metadata. Остальные поля добавляются, если данные есть в карточке товара и могут быть корректно преобразованы.

Откуда берутся данные товара

Виджет пытается найти значения в нескольких возможных полях товара.

Поле события	Поля товара
external_id	id, product_id, external_id, sku
product_id	числовое значение id, product_id, external_id или sku
product_name	title, name, product_name
price	price, current_price, new_price
currency	currency или валюта из настроек виджета
position	position
metadata.url	url, link, href

Если идентификатор товара не является положительным целым числом, он отправляется как external_id, но не дублируется в product_id.

Связь с поисковой сессией

После ответов /api/v1/search и /api/v1/search/suggests виджет сохраняет:

• search_id из поля search_id;
• search_id из поля autocomplete_id, если это ответ подсказок;
• session_id из поля session_id.

Эти значения добавляются в события клика. Так аналитика связывает конкретный клик с запросом, подсказками и выдачей пользователя.

Отправка события без блокировки перехода

События отправляются через fetch с параметром keepalive: true. Это позволяет браузеру продолжить отправку события даже если пользователь сразу переходит по ссылке товара.

Если отправка события завершилась ошибкой, виджет не показывает ошибку пользователю и не блокирует переход.

Как отключить переходы, но оставить события

Используйте data-disable-product-links="true", если карточки не должны быть ссылками.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="suggests"
    data-disable-product-links="true"
></div>

Клик по карточке все равно будет обработан виджетом. В подсказках карточка товара может работать как выбор подсказки, если у нее нет ссылки.

Ручная отправка событий через API

Если нужно отправлять дополнительные события, например add_to_cart или purchase, используйте тот же endpoint событий напрямую.

fetch('/api/v1/search/events', {
    method: 'POST',
    credentials: 'include',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({
        event_id: crypto.randomUUID(),
        event_type: 'add_to_cart',
        search_id: 'search-id',
        session_id: 'session-id',
        external_id: 'product-123',
        product_name: 'iPhone 15',
        price: 99990,
        currency: 'RUB',
        quantity: 1,
    }),
});

Для ручных событий используйте те же search_id и session_id, которые относятся к поисковой сессии пользователя.

Проверка событий

Чтобы проверить отправку аналитики:

1. Откройте страницу с виджетом.
2. Введите запрос и дождитесь товаров.
3. Откройте вкладку Network в инструментах браузера.
4. Кликните по товару.
5. Найдите запрос к /api/v1/search/events и проверьте payload.

Если события не уходят, проверьте API-ключ, eventUrl, CORS-настройки и наличие JavaScript-ошибок на странице.