Skip to content

Техническая документация. Персонализированный AI-каталог SearchBooster

1. Введение

Персонализированный AI-каталог — это API-продукт для построения персонализированной товарной выдачи в формате каталога.

В отличие от стандартных рекомендаций:

  • возвращает большое количество товаров;
  • поддерживает пагинацию;
  • поддерживает фильтрацию;
  • может использоваться как полноценная категория.

Интеграция выполняется только через API.

2. Быстрый старт

Минимальные шаги для запуска AI-каталога:

  1. Получить userId (из cookie searchbooster_v2_user_id)
  2. Выполнить API-запрос:
GET https://api4.searchbooster.io/api/{uuid}/widgets/{ID_WIDGET}?userId=USER_ID&limit=20&skip=0
  1. Отобразить товары из offers
  2. Использовать params для построения фильтров
  3. Использовать hits для пагинации

3. Назначение продукта

AI-каталог используется для:

  • персональной главной страницы;
  • персональной категории;
  • страницы «Рекомендуем»;
  • мобильного приложения;
  • персонализированных подборок.

AI-каталог может использоваться как замена стандартного каталога:

Обычный каталог: - одинаковый для всех пользователей

AI-каталог: - персонализирован под каждого пользователя - учитывает поведение и интересы - повышает конверсию и выручку

4. Архитектура и принцип работы

Схема:

Пользователь → API → SearchBooster → JSON → UI каталога

Источники данных:

  • поведение пользователя;
  • товарный фид;
  • категории;
  • параметры товаров;
  • регион;
  • наличие. Алгоритм формирует персонализированную выдачу на основе поведения конкретного пользователя и данных товарного каталога.

5. Требования к интеграции

Для корректной работы Персонализированного AI-каталога рекомендуется:

  • установить трекер SearchBooster на сайт;
  • передавать события пользователя;
  • использовать стабильный userId;
  • передавать categoryId, если AI-каталог должен работать внутри конкретной категории;
  • использовать limit и skip для пагинации;
  • использовать params для фильтрации;
  • использовать regionId, если цены и наличие зависят от региона.

5.1. Установка трекера

<script defer src="https://cdn2.searchbooster.net/scripts/tracker/{uuid}/searchbooster.js"></script>

{uuid} – uuid проекта. Доступен в Личном кабинете SearchBooster.

Трекер размещается в на всех страницах сайта.

Для персонализации наиболее важны события:

view_item – пользователь просматривает карточку товара; add_to_cart – пользователь добавляет товар в корзину; purchase – пользователь совершает покупку; add_to_wishlist – пользователь добавляет товар в избранное; begin_checkout – пользователь начинает оформление заказа.

6. Работа с API

Все запросы выполняются через REST API. Ответы возвращаются в формате JSON.

6.1 Пример API-запроса

GET https://api4.searchbooster.io/api/{uuid}/widgets/{ID_WIDGET}?userId=USER_ID&limit=18&skip=0

Пример:

https://api4.searchbooster.io/api/{uuid}/widgets/331?userId=xxx&categoryId=8145&limit=18&skip=0

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

  • {uuid} – uuid проекта. Обязательный параметр.
  • ID_WIDGET – id AI-каталога / виджета. Обязательный параметр.
  • userId – идентификатор пользователя. Рекомендуется передавать значение из cookie сайта с ключом searchbooster_v2_user_id. Обязательный параметр для персонализации. Если userId не передан, персонализация будет ограничена.
  • segmentId – сегмент пользователя или тип выдачи. Необязательный параметр. Например: rec.
  • categoryId – id категории из товарного фида. Необязательный параметр. Если передан, AI-каталог вернёт персонализированную выдачу внутри выбранной категории.
  • regionId – значение региона согласно товарному фиду. Необязательный параметр. Используется, если цены и наличие зависят от региона.
  • withNotAvailable – управление показом недоступных товаров. Необязательный параметр. false – возвращать только товары в наличии; true – возвращать товары в наличии и товары не в наличии.
  • limit – количество товаров в ответе. Необязательный параметр. Используется для пагинации.
  • skip – смещение от начала выдачи. Необязательный параметр. Используется для пагинации.
  • params – фильтры по параметрам товаров. Необязательный параметр.

6.3 Пагинация

Для построения каталожной выдачи используется пагинация через параметры: Пример первой страницы:

limit=18&skip=0

Пример второй страницы:

limit=18&skip=18

Пример третьей страницы:

limit=18&skip=36

Формула:

skip = (page - 1) * limit

6.4. Фильтрация и кастомизация

Фильтрация передаётся в параметре params. params — это готовые фильтры, которые необходимо отобразить на сайте.

Они формируются автоматически на основе товарного фида и текущей выдачи.

Пример фильтрации по значению параметра:

{"condition":"in","field":"качество","options":["Премиум"]}

Пример фильтрации по цене:

{"field":"price","min":"1000","max":"100000","condition":"range"}

Пример фильтрации по нескольким параметрам:

[
{"condition":"in","field":"гарантия","options":["12 месяцев"]},
{"field":"price","min":"10000","max":"150000","condition":"range"}
]

При передаче в URL значение params должно быть URL-encoded. Пример передачи params в URL (encoded):

params=%5B%7B%22condition%22%3A%22in%22%2C%22field%22%3A%22качество%22%2C%22options%22%3A%5B%22Премиум%22%5D%7D%5D

6.5. Ответ API

{
"offers": [...],
"params": [...],
"hits": 218
}

7. Поля ответа

offers – товары
params – фильтры
hits – общее количество

8. Пример товара

{
"available": true,
"id": "110353",
"name": "Товар",
"price": 1000,
"currency": "RUR",
"pictures": ["https://..."],
"category": {"id":"8145","name":"Категория"}
}

9. Фильтры (params)

Тип multiple:

{
"id":"качество",
"type":"multiple",
"options":[{"id":"Премиум","hits":52}]
}

Тип range:

{
"id":"price",
"type":"range",
"minValue":200,
"maxValue":198700
}

10. Отображение на стороне клиента

Пример логики frontend.

  1. Выполнить API-запрос.
  2. Отобразить товары из offers.
  3. Построить фильтры из params.
  4. При выборе фильтра — повторить запрос с params.
  5. При переходе по страницам — изменять skip.

Так как интеграция выполняется только через API, клиентская сторона самостоятельно отвечает за:

  • отрисовку карточек товаров;
  • отображение цен; отображение старых цен;
  • отображение изображений; построение фильтров;
  • построение пагинации; обработку кликов; переходы на карточки товаров;
  • отправку событий аналитики.

Рекомендуемый порядок работы:

1) Выполнить API-запрос. 2) Отобразить товары из массива offers. 3) Построить фильтры на основе массива params. 4) Построить пагинацию на основе hits, limit и skip. 5) При выборе фильтра повторно выполнить API-запрос с обновлённым params. 6) При переходе на следующую страницу повторно выполнить API-запрос с новым skip.

11. События и аналитика

Для оценки эффективности AI-каталога рекомендуется фиксировать события:

1) generate – запрос к API AI-каталога; 2) show – показ товара пользователю; 3) click – клик по товару; 4) addToCart – добавление товара в корзину; 5) addToWishlist – добавление товара в избранное; purchase – покупка.

Документация по событиям:

События могут использоваться:

  • для аналитики эффективности;
  • для улучшения персонализации; для обучения алгоритмов;
  • для оценки влияния AI-каталога на выручку.

Ограничений по количеству запросов за единицу времени нет.

12. Товарный фид

Для работы AI-каталога используется товарный фид проекта.

Фид должен содержать:

  • id товара;
  • название;
  • ссылку на карточку товара;
  • цену;
  • наличие;
  • категорию;
  • изображения;
  • параметры товаров;
  • региональные цены и остатки, если используется региональность.

Для подгрузки товаров может использоваться:

  • YML-фид;
  • Google Merchant Feed.

Документация по товарному фиду:

13. Коды ответов

  • 200 OK
  • 400 Bad Request
  • 404 Not Found
  • 500 Internal Server Error

14. Rate limits

Ограничений нет.

15. Товарный фид

Используется стандартный фид:

  • YML
  • Google Merchant

16. Best Practices

Рекомендуется:

  • всегда передавать userId;
  • использовать стабильный идентификатор пользователя между сессиями;
  • передавать categoryId, если AI-каталог размещается внутри категории;
  • использовать limit и skip для пагинации;
  • использовать hits для расчёта количества страниц;
  • ограничивать выдачу товарами в наличии, если недоступные товары не нужно показывать;
  • передавать regionId, если сайт использует региональные цены и остатки;
  • строить фильтры на основе массива params из ответа API;
  • логировать rid для диагностики спорных запросов; передавать события поведения пользователя для улучшения персонализации.

17. FAQ

  • Можно ли использовать AI-каталог без userId?

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

  • Чем AI-каталог отличается от персональных рекомендаций?

Персональные рекомендации обычно используются как небольшой товарный блок.

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

  • Можно ли использовать AI-каталог в мобильном приложении?

Да. Интеграция выполняется через API, поэтому AI-каталог можно использовать на сайте, в мобильном приложении или во внутреннем интерфейсе.

  • Можно ли фильтровать выдачу?

Да. Для этого используется параметр params.

  • Можно ли строить фильтры на стороне сайта?

Да. В ответе API возвращается массив params, который можно использовать для построения фильтров.

  • Можно ли использовать региональные цены и остатки?

Да. Для этого нужно передавать regionId, соответствующий региону в товарном фиде.

18. Поддержка

По вопросам интеграции и настройки Персонализированного AI-каталога обращайтесь в техническую поддержку SearchBooster.