Skip to content

Техническая документация. Виджеты рекомендаций SearchBooster

1. Введение

Виджеты рекомендаций SearchBooster позволяют интернет-магазинам увеличивать конверсию, средний чек и удержание пользователей за счёт персонализированных товарных блоков.

Система использует машинное обучение в реальном времени, данные о поведении пользователей и товарный каталог.

Доступные типы рекомендаций:

  • Персональные рекомендации – индивидуальные подборки для каждого пользователя.

  • Сопутствующие товары – кросс-селл, товары «с этим покупают».

  • Похожие по фото товары – рекомендации визуально похожих товаров.

  • Недавно просмотренные – товары, которые пользователь смотрел ранее.

  • Похожие по описанию товары - отображает товары похожие по описанию, что и просматриваемый товар.

  • Товары со скидкой - показывает товары со скидками. Доступен вариант с персонализированным показом товаров.

  • Популярные товары – показывает наиболее актуальные и востребованные товары. Доступен вариант с персонализированным показом товаров.

  • Популярные в категории - отображает самые популярные товары в выбранной категории. Доступен вариант с персонализированным показом товаров.

2. Типы виджетов

2.1. Персональные рекомендации

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

Рекомендации по размещению:

  • Главная.

  • Страница категории.

  • Страница товара.

  • Корзина.

  • Избранное.

  • Страница 404.

Особенности:

  • Персонализированный по умолчанию.

  • Может быть ограничен фильтрами (наличии, по бренду, по тегам фида).

2.2. Сопутствующие товары («С этим покупают»)

Формируется на основе данных о покупках и ассоциативных правилах - какие товары чаще всего покупают вместе.

Рекомендации по размещению:

  • Страница товара.

  • Корзина.

Особенности:

  • Может использоваться как блок cross-sell.

  • Поддерживает фильтрацию по категориям, брендам, ценовым диапазонам.

  • Является персонализированным виджетом.

2.3. Похожие по фото товары

Работает на основе векторного поиска. Система анализирует изображение товара и находит визуально похожие товары.

Рекомендации по размещению:

  • Страница товара.

Особенности:

  • Технология real-time поиска по embeddings.

  • Можно ограничить выборку (например, только в наличии).

2.4. Недавно просмотренные товары

Показывает товары, которые конкретный посетитель просматривал на сайте. Если история отсутствует, блок не отображается.

Рекомендации по размещению:

  • Главная.

  • Страница категории.

  • Страница товара.

  • Корзина.

  • Избранное.

  • Страница 404.

Особенности:

  • Строится на данных трекера.

  • Показывает историю просмотров.

2.5. Похожие по описанию товары

Отображает товары похожие по описанию, что и просматриваемый товар. Если в категории нет скидок, блок скрывается.

Рекомендации по размещению:

  • Страница товара.

Особенности:

  • Не является персонализированным.

2.6. Товары со скидкой

Показывает товары со скидками. Если нет акций, виджет скрывается. Доступен вариант с персонализированным показом товаров.

Рекомендации по размещению:

  • Главная.

  • Страница категории.

  • Страница товара.

Особенности:

  • Доступен вариант показа персонализированного виджета (будет учитывать предпочтения пользователя и показывать акционные товары, релевантные именно ему).

2.7. Популярные товары

Формируется на основе формулы ранжирования (покупки, просмотры, маржинальность и др.). Показывает наиболее актуальные и востребованные товары. Доступен вариант с персонализированным показом товаров.

Рекомендации по размещению:

  • Главная.

  • Страница категории.

  • Страница товара.

  • Корзина.

  • Страница 404.

Особенности:

  • Доступен вариант показа персонализированного виджета - ранжирование будет строиться на базе истории конкретного пользователя + фильтрация по тегу <param name="Хит">Да</param>.

2.8. Популярные в категории

Отображает самые популярные товары в выбранной категории.

Рекомендации по размещению:

  • Страница категории.

  • Страница товара.

Особенности:

  • Доступен вариант показа персонализированного виджета (например, «Популярные в категории + учитываем предпочтения пользователя»).

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

Схема работы:

Источник данных → Алгоритм рекомендаций → API → Отображение на сайте

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

  • События пользователя на сайте, переданные в контейнер dataLayer (события view_item, add_to_cart, purchase и др.).

  • Товарный фид (с атрибутами: категория, цена, бренд, теги param name и др.).

  • Региональные данные (regionId).

Алгоритмы:

  • Модели машинного обучения с дообучением в real-time.

  • Ассоциативные правила («с этим покупают»).

  • Визуальная похожесть (по фото).

  • Фильтрация (наличие, категория, бренд, теги).

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

Обновление данных:

  • В реальном времени (через трекер и API).

  • Возможность ограничивать выдачу товарами в наличии или по любым параметрам фида.

4. Требования к интеграции на сайте

Для работы всех виджетов необходимо:

  • Установить трекер.

  • Подключить скрипт виджетов.

  • Разместить HTML-код виджетов на нужных страницах.

Данные для установки предоставляются в процессе интеграции.

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

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

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

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

Трекер собирает данные, которые передаются в контейнер dataLayer сайта.

Для рекомендаций самыми важными событиями являются:

  • view_item – пользователь просматривает страницу товара;

  • purchase - пользователь совершает покупку;

  • add_to_cart - пользователь добавляет товар в корзину;

  • add_to_wishlist - пользователь добавляет товары в wishlist;

  • begin_checkout - пользователь начинает оформление покупки.

Требования к разметке событий - документация.

4.2. Подключение скрипта виджетов

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

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

4.3. Установка HTML-кода виджетов

4.3.1. «Персональные рекомендации»

<sb-widget id="ID" category-id="0" with-not-available="false"/>
  • ID – id виджета в личном кабинете.
  • category-id="0" - id категории, где 0 означает использование виджета без категории.
  • with-not-available="false" - для показа товаров только в наличии.

4.3.2. «Сопутствующие товары»

<sb-widget id="ID" product-id="PRODUCT_ID"/>
  • PRODUCT_ID – id товара, для которого нужно найти похожие товары. PRODUCT_ID должен соответствовать id товара в Товарном фиде.

4.3.3. «Похожие товары по фото»

<sb-widget id="ID" product-id="PRODUCT_ID" category-id="0"/>

4.3.4. «Недавно просмотренные»

<sb-widget id="ID"/>

4.3.5. «Похожие по описанию товары»

<sb-widget id="ID" product-id="PRODUCT_ID" category-id="0"/>

4.3.6. «Товары со скидкой»

<sb-widget id="ID" category-id="0"/>

4.3.7. «Популярные товары»

<sb-widget id="ID" category-id="0"/>

4.3.8. «Популярные в категории»

<sb-widget id="ID" category-id="0"/>

4.4. Атрибуты виджетов

Атрибуты виджетов:

  • ID – уникальный идентификатор блока. Обязательный.

  • product-id – ID товара. Обязательный для виджетов: Сопутствующие товары, Похожие по фото товары, Похожие по описанию товары.

  • category-id – ID категории (0 = без категории). Необязательный.

  • vendors – фильтрация по брендам. Необязательный.

  • withNotAvailable=true – показ товаров без наличия. Если нет артибута, по умолчанию, показываются только товары доступные для покупки. Необязательный.

5. Работа с API

Все запросы выполняются по протоколу REST API (HTTPS). Ответы возвращаются в формате JSON.

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

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

GET https://api4.searchbooster.io/api/{uuid}/widgets/{ID_WIDGET}?id=208913817&userId=USER_ID&limit=10&params=[{"condition":"equal","field":"Материал","value":"золото"}]

Параметры:

  • {uuid} – uuid проекта. Доступен в Личном кабинете SearchBooster. Обязательный параметр.

  • ID_WIDGET - уникальный идентификатор блока. Обязательный параметр.

  • id – ID товара. Обязательный параметр для виджетов: Сопутствующие товары, Похожие по фото товары, Похожие по описанию товары.

  • categoryId – id категории из товарного фида. Обязательный параметр для виджетов: “Популярные в категории”. Для остальных не является обязательным;

  • userId – идентификатор пользователя. Рекомендуем указывать значение из cookie сайта с ключем searchbooster_v2_user_id. Запись в данный ключ производится трекером или поисковым виджетом SearchBooster.

  • segmentId – параметр для сегментации пользователей. Необязательный параметр.

  • regionId – учёт региона. Необязательный параметр.

  • limit – количество товаров. Необязательный параметр.

  • params – фильтрация. Необязательный параметр.

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

По параметрам фида:

{"condition":"equal","field":"Материал","value":"золото"}

По цене:

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

Исключение аксессуаров:

<param name="isAccessory">False</param>

Сортировка и формулы ранжирования (пример для популярных товаров):

{"script": "return doc['widgetEvents.purchase'].value * 10 + doc['widgetEvents.add_to_cart'].value", "boost_mode": "multiply"}

5.3. Ответы API и коды ошибок

Пример успешного ответа (200 OK):

{
  "offers": [
    {
    "available": true,
    "offerCode": "fj56",
    "id": "123",
    "score": 11.966,
    "vendor": "vendor",
    "name": "Диван прямой",
    "url": "https://searchboster.io/catalog/pryamye_divany ",
    "price": 117990,
    "currency": "RUB",
    "pictures": [
        " https://searchboster.io/catalog/pryamye_divany1.jpeg"
    ],
    "category": {
        "id": "100",
        "name": "Прямые диваны"
    },
    "categories": [
        {
        "id": "100",
        "name": "Прямые диваны"
        },
        {
        "id": "101",
        "name": "Мягкая мебель"
        },
    ],
    "groupedParams": {
        "bestsaller": [
        "true"
        ],
        "vendorCode": [
        "777"
        ],
        "Артикул": [
        "М777"
        ],
        "Базовый цвет": [
        "81400D "
        ],
        "Ширина": [
        "198"
        ]
    },
    "isPickup": false,
    "isDelivery": true,
    "isPreorder": false,
    "description": ""
    }
  ]
}

Коды ответов:

  • 200 OK – успешный ответ.

  • 400 Bad Request – некорректный запрос (ошибки в параметрах).

  • 404 Not Found – виджет или проект не найден.

  • 500 Internal Server Error – внутренняя ошибка сервера.

5.4. Rate limits

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

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

Собираемые события:

  • generate – запрос на генерацию рекомендаций по API;

  • show – показ блока;

  • click – клик по товару;

  • add_to_cart – добавление в корзину;

  • add_to_wishlist – добавление в избранное.

Запись событий производиться в базе данных ClickHouse (widget_events, dl_events). Дополнительно можно реализовать отправку событий в клиентские системы аналитики, например, Яндекс Метрика.

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

Для подгрузки товаров может использоваться как файл в формате YML, так и в формате Google Merchant Feed. Файл должен быть доступен к скачиванию по гиперссылке.

Ссылка на документацию по товарному фиду - подробнее.

8. Тестирование (Chrome User JS & CSS)

Вариант тестирования виджетов без установки. Требуется браузер Google Chrome и плагин User JavaScript and CSS.

Рассмотрим два варианта установки виджетов:

  • Простой вариант.

  • Вариант с передачей атрибутов.

1)Установка простого варианта

const script = document.createElement('script');
script.src = "https://cdn2.searchbooster.net/scripts/widgets/{uuid} /searchbooster.js";
document.head.appendChild(script);
const widget = document.createElement('sb-widget');
widget.setAttribute('id', 'ID_WIDGET');
document.body.prepend(widget);

Описание:

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

  • ID_WIDGET - уникальный идентификатор блока;

Данный код заменяет JS-скрипт:

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

и HTML-код:

<sb-widget id="ID_WIDGET"/>

2)Установка варианта с передачей атрибутов

const script = document.createElement('script');
script.src = "https://cdn2.searchbooster.net/scripts/widgets/{uuid} /searchbooster.js";
document.head.appendChild(script);
const widget = document.createElement('sb-widget');
widget.id = "ID_WIDGET";
widget.setAttribute('category-id', "ID_CATEGORY")
document.body.prepend(widget);

Описание: ID_CATEGORY – id категории из товарного фида;

Данный код заменяет JS-скрипт:

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

и HTML-код:

<sb-widget id="ID_WIDGET" category-id="ID_CATEGORY"/>

9. Часто задаваемые вопросы (FAQ)

Работает ли трекер в Safari? – Да, сбор через DataLayer аналогичен GA/Я.Метрике.

Можно ли передавать события не через DataLayer? – Да, через API.

Сколько нужно данных для обучения? – Рекомендуется: сотни тысяч товаров и тысячи корзин. Но можно запуститься без данных и собирать данные трекером.

10. Best Practices

Устанавливать виджеты на ключевые страницы: главная, категории, карточка товара.

Ограничивать выдачу товарами в наличии (available=true).

Для fashion использовать фильтры по параметрам (цвет, материал, коллекция).

Для электроники – кросс-селл («с этим покупают»).

Для ювелирной отрасли – фильтры по металлу, вставкам и коллекциям.

Регулярно проверять работу виджетов в ЛК (графики активности API).

11. Поддержка

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