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 — Идентификатор сессии (необязательный).

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

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": "view_item",
    "user_id": "L407EDDe_aiEp2DyUR1s5_wAKA6WoMlm6OscI8_79wU|6.22.10.56",    
    "items": [
      {
        "item_id": "568053",
        "price": 12599,
        "item_category": "Потолочные люстры"
      }
    ],
    "value": 12599,
    "currency": "RUB",
    "session_id": ""
  }'

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

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",  
    "items": [
      {
        "item_id": "568053",
        "price": 12599,
        "item_category": "Потолочные люстры"
      }
    ],
    "value": 12599,
    "currency": "RUB",
    "session_id": ""
  }'

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

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_wishlist",
    "user_id": "L407EDDe_aiEp2DyUR1s5_wAKA6WoMlm6OscI8_79wU|6.22.10.56",  
    "items": [
      {
        "item_id": "568053",
        "price": 12599,
        "item_category": "Потолочные люстры"
      }
    ],
    "value": 12599,
    "currency": "RUB",
    "session_id": ""
  }'

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

curl --location --request POST 'https://api4.searchbooster.io/api/ca8fc618-9ee9-48f1-b9b6-92e810424297/event/datalayer.json' \
--header 'accept: application/json, text/plain, */*' \
--header 'content-type: application/json' \
--data '{
    "event": "purchase",
    "user_id": "L407EDDe_aiEp2DyUR1s5_wAKA6WoMlm6OscI8_79wU|6.22.10.56",  
    "items": [
      {
        "item_id": "568053",
        "price": 10000,
        "item_category": "Потолочные люстры",
        "quantity": 3
      },
      {
        "item_id": "700000",
        "price": 12000,
        "item_category": "Бра",
        "quantity": 1
      }
    ],
    "value": 42000,
    "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 метода необходимо выполнить следующие шаги:

1. Получение основного токена:

2. Токен можно получить по ссылке: https://admin.searchbooster.io/profile

3. Получение токена статистики:

4. Необходимо осуществить запрос, указав 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'

Запрос к статистике (пример для запросов с нулевыми результатами): - Выполните curl запрос, указав токен статистики, полученный на предыдущем шаге:

curl 'https://cube.searchbooster.net/cubejs-api/v1/load?query={"measures":["Queries.count"],"order":{"Queries.count":"desc"},"filters":[{"member":"Queries.client","operator":"notEquals","values":["admin.searchbooster.io","admin.searchbooster.net"]},{"member":"Queries.hits","operator":"equals","values":["0"]},{"member":"Queries.merchandisings","operator":"notEquals","values":["redirect"]},{"member":"Queries.query","operator":"notEquals","values":[""]},{"member":"Queries.params","operator":"equals","values":["","null","[]"]}],"dimensions":["Queries.lowerQuery"],"timeDimensions":[{"dimension":"Queries.date","dateRange":["2025-09-14T00:00:00.000Z","2025-10-14T23:59:59.999Z"],"granularity":null}],"limit":100}&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'

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