API для передачи событий

Передача событий через Data Layer

Для передачи событий, связанных с взаимодействием пользователя с элементами интерфейса (например, добавление товара в корзину), используется POST-метод:

/api/{uuid}/event/datalayer.json

Параметры запроса:

Заголовки:
accept: application/json, text/plain, */*
content-type: application/json
user-agent: {User-Agent браузера пользователя}
Тело запроса (JSON):
event — Тип события (например, add_to_cart, purchase, view_item и т.д.). Список поддерживаемых событий соответствует структуре Google Data Layer E-commerce events. Подробнее: Google Data Layer.
user_id — Уникальный идентификатор пользователя.
widget_id — Идентификатор виджета, который можно найти в личном кабинете.
items — Массив объектов, описывающих товары:
- item_id — Идентификатор товара.
- price — Цена товара.
- item_category — Категория товара.
value — Общая стоимость товаров в корзине.
currency — Валюта (например, RUB).
session_id — Идентификатор сессии (необязательный).

Пример запроса:

curl 'https://api4.searchbooster.io/api/ca8fc618-9ee9-48f1-b9b6-92e810424297/event/datalayer.json' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  --data-raw '{
    "event": "add_to_cart",
    "user_id": "L407EDDe_aiEp2DyUR1s5_wAKA6WoMlm6OscI8_79wU|6.22.10.56",
    "widget_id": 156,
    "items": [
      {
        "item_id": "568053",
        "price": 12599,
        "item_category": "Потолочные люстры"
      }
    ],
    "value": 12599,
    "currency": "RUB",
    "session_id": ""
  }'

Передача событий о поиске

Данные следует передавать для формирования корректной статистики. Для фиксации пользовательских действий (клики, добавления в корзину и т. д.) используется GET-метод:

/api/{uuid}/event/click.json

Информация передаётся через GET-параметры.

Основные параметры

type — тип события:
productClick — клик по товару в результатах поиска;
- productClickCompletions — клик по товару в подсказках;
- categoryClick — клик по категорийной подсказке;
- specialOfferClick — клик по спецпредложению;
- suggestionsClick — клик по подсказке «suggestions»;
- popularClick — клик по популярным подсказкам;
- brandClick — клик по бренду;
- historyClick — клик по подсказке «История»;
- addToCart — добавление товара в корзину из поиска;
- addToWishlist — добавление товара в избранное из поиска.
entityId — идентификатор объекта (например, ID товара или название бренда).
params — JSON-объект с дополнительными параметрами:
- offerId — ID товара (опционально);
- pos — позиция объекта в выдаче (опционально);
- row — номер строки выдачи (опционально);
- col — номер колонки выдачи (опционально);
- clickType — click (обычный клик) или contextmenu (контекстное меню).

Технические параметры

userId — уникальный идентификатор пользователя. Необязательный параметр.
searchId — ID поисковой сессии. Необязательный параметр.
queryId — ID конкретного запроса. Необязательный параметр.

⚠️ Эти параметры должны быть уникальными, чтобы корректно отрабатывали механизмы ранжирования.

Значение параметра userId должно совпадать со значением cookie searchbooster_v2_user_id, установленного у пользователя.

Cookie searchbooster_v2_user_id может быть создано:

автоматически поисковым виджетом SearchBooster;
трекером событий SearchBooster;
вручную на стороне сайта (например, при генерации собственного идентификатора).

Использование единого значения userId гарантирует корректную персонализацию поиска и сбор статистики.

Дополнительный параметр client

Позволяет определить устройство/среду, где произошло событие:

desktop — десктоп;
mobile_ios — мобильный браузер (iOS);
mobile_android — мобильный браузер (Android);
mobile_app_ios — мобильное приложение iOS;
mobile_app_android — мобильное приложение Android.

Допустимо использовать и собственные значения client.

Важные события для передачи

1) Клики на товары в результатах поиска (type=productClick). Используются для расчёта CTR и средней позиции клика. Доступны в ЛК → «Статистика».

Пример запроса:

curl --location --globoff --request GET \
'https://api.searchbooster.net/api/{uuid}/event/click.json?type=productClick&params={"offerId":"4596532","pos":1,"row":1,"col":1,"clickType":"click"}&userId=<USER_ID>&client=mobile_app_ios'`

2) Клики на товары в подсказках (type=productClickCompletions).

curl --location --globoff --request GET \
'https://api.searchbooster.net/api/{uuid}/event/click.json?type=productClickCompletions&params={"offerId":"4596532","pos":1,"row":1,"col":1,"clickType":"click"}&userId=<USER_ID>&client=mobile_app_ios'

3) Добавление в корзину из поиска (type=addToCart).

curl --location --globoff --request GET \
'https://api.searchbooster.net/api/{uuid}/event/click.json?type=addToCart&params={"offerId":"4596532"}&userId=<USER_ID>&client=mobile_app_ios'

4) Добавление в избранное из поиска (type=addToWishlist).

curl --location --globoff --request GET \
'https://api.searchbooster.net/api/{uuid}/event/click.json?type=addToWishlist&params={"offerId":"4596532"}&userId=<USER_ID>&client=mobile_app_ios'

Пример клика по бренду

curl --location --globoff --request GET \
'https://api.searchbooster.net/api/{uuid}/event/click.json?type=brandClick&params={"pos":"1","clickType":"click"}&entityId=brandName&userId=<USER_ID>&client=desktop'

API получения статистики

Для использования данного API метода необходимо выполнить следующие шаги:

Получение основного токена:
Токен можно получить по ссылке: https://admin.searchbooster.io/profile
Получение токена статистики:
Необходимо осуществить запрос, указав UUID_проекта и основной токен, используя следующий curl запрос:

     curl 'https://web4.searchbooster.io/api/sources/<UUID_проекта>' \
       -H 'accept: application/json' \
       -H 'authorization: Bearer ОСНОВНОЙ_ТОКЕН' \
       -H 'origin: https://admin.searchbooster.io'

В ответе на запрос необходимо взять токен статистики из параметра data.statJwt. Токен статистики действителен в течение 1 суток.
Запрос к статистике (пример для популярных запросов):
Выполните curl запрос, указав токен статистики, полученный на предыдущем шаге:

curl 'https://cube.searchbooster.net/cubejs-api/v1/load?query={"measures":["Queries.count"],"filters":[{"member":"Queries.firstInSession","operator":"equals","values":["1"]},{"member":"Queries.type","operator":"equals","values":["search"]}],"order":{"Queries.count":"desc"},"dimensions":["Queries.lowerQuery"],"timeDimensions":[{"dimension":"Queries.date","dateRange":["2024-07-01T00:00:00.000Z","2024-07-31T00:00:00.000Z"],"granularity":null}],"limit":1000}&queryType=multi' \
       -H 'accept: */*' \
       -H 'accept-language: ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7' \
       -H 'authorization: <ТОКЕН_СТАТИСТИКИ>' \
       -H 'origin: https://admin.searchbooster.io'

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