Перейти к содержимому
SearchBooster Docs

Настройки поискового виджета

Большая часть настроек виджета задаётся формой в личном кабинете (Виджет). Всё, чего нет в форме, можно передать в поле «Дополнительные опции» (JSON) — оно добавляется к настройкам при сохранении. Функции (хуки корзины, обработчики) в JSON не передаются — их задают в своём коде инициализации (см. пример).

window.searchbooster({
  apiKey: 'PROJECT_UUID',
  locale: 'ru',
  theme: { variables: { 'color-primary': '#E30613' } },
  completions: { isShowAfterInputFieldFocus: true },
  search: { image: true, limit: 24 },
  initialized(sb) {
    sb.mount({ widget: 'search-popup', selector: '#search-input' });
    sb.on('search', ({ query, search }) => console.log(query.query, search?.hits));
  },
});

Настройки сливаются со значениями по умолчанию глубоко: объекты дополняются, массивы склеиваются, а не заменяются.

Основное

Заголовок раздела «Основное»
Опция Тип По умолчанию Описание
apiKey string — UUID проекта. Подставляется личным кабинетом.
apiUrl string https://api.searchbooster.net Адрес API. При недоступности виджет сам пробует https://api4.searchbooster.io.
locale string язык браузера ru, en, kz, uk, de, pl, it, fr, fi, es, cz, tr, pt, lt, lv. Неизвестное значение → ru.
regionId string | function — Регион. Функция вызывается перед каждым запросом. Обычно задаётся через var sbRegionId.
segmentId string | function — Сегмент посетителя. Через var sbSegmentId.
userId string — Свой ID посетителя. Через var sbUserId.
userIdCookieName string — Имя cookie вашего сайта, из которой брать ID посетителя (чтобы совпадал с трекером и CRM).
queryParams object {} Дополнительные параметры ко всем запросам API, например { "sortKey": "new" }.
isActiveIntegrationMode bool false Режим интеграции: виджет работает только у тех, кто открыл сайт с ?sbdemo=true (cookie на 30 дней). Для проверки на проде до запуска.
mode string auto mobile / web — принудительно мобильный или десктопный интерфейс.
initialized function(sb) — Вызывается после загрузки; внутри — sb.mount(...) и sb.on(...).

Окно поиска

Заголовок раздела «Окно поиска»
Опция Тип По умолчанию Описание
popup bool true true — полноэкранное окно по клику на поле сайта; false — виджет встраивается внутрь элемента selector и открыт сразу.
logoSrc URL — Логотип слева от поля в окне (десктоп).
closePopupIcon SVG — Своя иконка закрытия.
inputPlaceholder {isAnimated, placeholderTexts[]} — Анимированный placeholder с перебором подсказок: {"isAnimated":true,"placeholderTexts":["корм для щенка","поводок"]}.
viewPortOptimise bool | string true Пока окно открыто, подменяет <meta name="viewport"> (чтобы iOS не зумил поле). Строка — своё значение content.
compensateScrollbar bool false Компенсировать ширину скроллбара при блокировке прокрутки страницы.
fixScroll bool false Зафиксировать ширину страницы на десктопе, чтобы она не «прыгала».
saveSearchStateOnClick bool false При повторном открытии подставлять последний запрос.
blockFirstResultsPopupQuery bool false Не открывать окно автоматически, если в URL есть состояние поиска.
customSvgIconRightArrow SVG — Иконка стрелки каруселей.
scrollToTopBtn {bottomOffset, rightOffset, threshold, zIndex} — Кнопка «Наверх» в выдаче.

Подсказки

Заголовок раздела «Подсказки»
Опция Тип По умолчанию Описание
completions bool | object включены false — отключить подсказки.
completions.isShowAfterInputFieldFocus bool false Показывать подсказки сразу при фокусе (история и популярное).
completions.showCompletionsLabel bool false Заголовки групп («Категории», «Бренды»).
completions.showPopularOffersLabel bool false Заголовок блока товаров.
completions.oneColumnMode bool false Подсказки в одну колонку.
completions.isShowCloseButton bool false Кнопка закрытия подсказок.
completions.suggestionsAsQuery bool false Клик по подсказке-запросу подставляет её текст в поле.
completions.taps.desktop / .mobile {active, count} — Чипсы-уточнения в подсказках.
completionSettings object — Состав и порядок блоков — как в API подсказок.
completionsFullWidth bool false Подсказки на всю ширину, товары плиткой.
imagesSize {width, height} 500×500 Размер картинок товаров в подсказках при completionsFullWidth.
showPopularQueries bool false Популярные запросы при пустой выдаче.
skuConfig.skuOfferPaths string[] ["params.sku", "offerCode"]… Где в товаре искать артикул для подсветки точного совпадения.

Выдача и карточки

Заголовок раздела «Выдача и карточки»
Опция Тип По умолчанию Описание
search.limit number 24 Товаров на странице.
search.groupCategories bool true Группировать выдачу по категориям (карусели).
search.groupByCategoriesSize number 10 Товаров в группе.
search.catalog bool true Кнопка каталога (рубрикатора).
search.digest bool | {offersLimit, collapsedLines} false AI-резюме над выдачей (функция включается для проекта).
search.queryUnderstanding {enabled, excludeQueries[]} выкл. Автоматически выставлять фильтры из запроса («белая собака до 5000»).
search.stateManager hash | param hash Как хранить состояние поиска в URL: #/query=… или ?searchbooster={…}.
useHistoryPushState bool true pushState (кнопка «Назад» возвращает к прошлому поиску) или replaceState.
linkTargetBlank bool false Открывать товары в новой вкладке.
errorImg URL — Заглушка для товаров без фото.
offer.placesForLayout object — Вид карточки по месту: {"results":"column","mobileResults":"column","completions":"rowMini"}. Варианты: row, column, rowMini, columnMini.
offer.currency string из фида Символ валюты вместо значения из фида.
offer.minimumFractionDigits number 0 Минимум знаков после запятой в цене.
offer.reviews {variant: 'single' | 'stars', showZeroWhenMissing} — Блок рейтинга.
offer.trackClicks bool true Отправлять клики по товарам в аналитику.
offer.taps.desktop / .mobile {active, count} — Чипсы-уточнения над выдачей.
layout.resultsBreakpoints {ширина: {columnCount, gridGap, rowGap}} — Адаптивная сетка: {"0":{"columnCount":2},"768":{"columnCount":3},"1200":{"columnCount":4}}.
layout.gridGap, layout.rowGap number 16, 24 Отступы сетки.
popularOffersWhenNoResults.limit number 8 Сколько популярных товаров показать при пустой выдаче.
personalRecommendationsWidget {widgetId} — Показывать виджет рекомендаций при пустом запросе и пустой выдаче.
hideExtraOffersOnSkuMatch bool false При точном совпадении по артикулу показывать только этот товар.
isActiveAutoCategorySelection bool true Автоматически выбирать категорию, если запрос явно про неё.

Фильтры и сортировка

Заголовок раздела «Фильтры и сортировка»
Опция Тип По умолчанию Описание
layout.filterPosition left | top left (из кабинета) Фильтры слева или над выдачей.
hiddenFilters string[] [] Скрыть фильтры по названию параметра.
sortFilters string[] [] Порядок фильтров.
filterConfig {фильтр: {isShort, hasSearch, unit}} — Настройки отдельного фильтра: свёрнутый список, поиск по значениям, единица измерения.
isShortFilterView bool false Показывать первые значения фильтров, остальные — по «Ещё».
categoriesAsTree bool false Категории деревом.
showCategoryImagesInFilters bool false Картинки категорий в фильтре.
colorPreview bool | {targets[], palette{}} false Цветные кружки вместо названий цвета. true — для параметра «Цвет»; palette — свои HEX для значений.
hideFiltersIfSingleOffer bool true Не показывать фильтры, если найден один товар.
scrollToTopAfterFilterChange bool true Прокручивать выдачу вверх после выбора фильтра.
sort.visible bool true Меню сортировки.
sort.default {sortBy, sortDest} релевантность Сортировка по умолчанию.
sort.additionalOptions {ключ: {param, ASC, DESC}} — Свои варианты сортировки (по формулам из кабинета).
sort.disableOptions array [] Убрать варианты сортировки, например ["available"].

Поиск по фото и голосом

Заголовок раздела «Поиск по фото и голосом»
Опция Тип По умолчанию Описание
search.image bool false Кнопка поиска по фото в поле (функция тарифа).
isShowImageSearchInFilters bool false Блок поиска по фото над фильтрами (при filterPosition: "left").
segmentIdImageSearch string — Отдельный сегмент для поиска по фото.
search.voice bool false Голосовой ввод (в браузерах с SpeechRecognition).

Тексты

Заголовок раздела «Тексты»

locales переопределяет любые строки интерфейса для языка. Строка из пробела " " скрывает текст.

{
  "locales": {
    "ru": {
      "results": { "popularOffers": "Возможно, вас заинтересует" }
    }
  }
}

Основные тексты редактируются в личном кабинете на вкладке «Текстовые значения».

Оформление

Заголовок раздела «Оформление»

Цвета и шрифты

Заголовок раздела «Цвета и шрифты»
{
  "theme": {
    "variables": {
      "color-primary": "#E30613",
      "color-background": "#ffffff",
      "color-text-primary": "#1d1d1f",
      "font-family-primary": "Inter, sans-serif",
      "search-input-height": "48px",
      "button-border-radius": "8px"
    }
  }
}

Значение "$--my-brand" берёт цвет из CSS-переменной --my-brand вашего сайта. Для HEX-цветов виджет сам рассчитает оттенки (светлее, прозрачные).

Группа Переменные
Цвета color-primary, color-secondary, color-background, color-background-primary, color-background-secondary, color-text-primary, color-text-secondary, color-text-light, color-success, color-danger, color-border, color-shadow
Шрифты font-family-primary, font-family-secondary, font-size, font-size-lg, font-size-md, font-size-sm, font-size-xs, font-weight
Размеры search-popup-max-width, search-input-height, search-input-padding-x, search-layout-border-radius, completions-item-border-radius, button-border-radius, offer-price-font-size, box-shadow, transition-time

Свой CSS

Заголовок раздела «Свой CSS»

Виджет рендерится в Shadow DOM, поэтому стили сайта на него не действуют. Свой CSS пишется в поле «Кастомизация» в личном кабинете (или в <style class="l-ss-styles"> на странице до загрузки виджета) — он копируется внутрь виджета.

.l-ss-c-offer-title { font-weight: 600; }
.l-ss-c-offer-price { color: #E30613; }
.l-ss-c-offer-label-type-hit { background: #ffb800; }
.l-ss-c-is-mobile .l-ss-c-search-popup-content { padding: 8px; }
Элемент Классы
Окно l-ss-c-search-popup, -content, -top-section, -logo, -mask
Поле l-ss-c-input, l-ss-c-input-wrapper, l-ss-c-input-clear
Подсказки l-ss-c-completions-wrapper, -item, -group, -group-label
Выдача l-ss-c-results, l-ss-c-results-info, l-ss-c-results-empty, l-ss-c-offers-wrapper-grid
Карточка l-ss-c-offer, -image, -title, -price, -old-amount, -sale, -label, -label-type-{id}, -cart-btn
Фильтры l-ss-c-filters-left, l-ss-c-filters-top-container, l-ss-c-filter-enum, l-ss-c-sort
Состояния на body: l-ss-c-popup-is-active, l-ss-c-is-mobile

Корзина, избранное, сравнение

Заголовок раздела «Корзина, избранное, сравнение»

Чтобы кнопка «В корзину» в виджете работала с корзиной сайта, передайте хуки в offer.cart (функциями — в своём коде инициализации):

offer: {
  cart: {
    // текущая корзина: { id: количество } или [{ id, quantity }]
    items: async () => ({ '110166': 1 }),
    // изменение количества; верните новое количество
    onChangeOfferCount: async ({ operationType, currentQuantity, ...offer }) => {
      const next = { add: 1, inc: currentQuantity + 1, dec: currentQuantity - 1, removeAll: 0 }[operationType];
      await myShop.cart.set(offer.id, next);
      return next;
    },
    onGoToCart: () => (location.href = '/cart'),
    // своя кнопка, например для товаров не в наличии
    addToCartConfig: async (offer) => (offer.available ? undefined : { label: 'Подробнее', action: () => (location.href = offer.url) }),
  },
  favourites: {
    items: async () => ({ '110166': true }),
    onChange: async ({ isFavourite, ...offer }) => { await myShop.favourites.toggle(offer.id, isFavourite); return isFavourite; },
  },
},
cartCount: { offer: { count: true } }, // счётчик «− N +» вместо кнопки в выдаче

Корзина изменилась вне виджета — сообщите ему:

window.sbEvents.pushEvent('UPDATE_CART', { '110166': 2, '99839': 0 }); // изменённые товары
window.sbEvents.pushEvent('UPDATE_CART');                              // перечитать items() целиком

Так же работают UPDATE_FAVOURITES и UPDATE_COMPARE. Для периодического перечитывания корзины: offer.cart.usePollingRate: true и offer.cart.pollingRate в мс.

JS API

Заголовок раздела «JS API»

Объект sb приходит в initialized(sb) и доступен как window.searchbooster.api.

Метод Описание
sb.mount(options) Подключить виджет к элементу.
sb.on(event, callback) Подписаться на событие (ниже).
sb.open() / sb.close() Открыть или закрыть окно поиска. sb.open({ openImageSearch: true }) — сразу поиск по фото.
sb.reinit() Переподключить виджет после перерисовки страницы (SPA).
sb.setQueryParam(name, value) Добавить параметр ко всем запросам API.
sb.pushEvent(name, data) То же, что window.sbEvents.pushEvent.

sb.mount

Заголовок раздела «sb.mount»
Опция Описание
widget search-popup (поле + окно, по умолчанию), search-results (блок выдачи на вашей странице), completions (только подсказки), image-search-similar (кнопка «Похожие» на фото товара).
selector CSS-селектор поля поиска сайта; несколько — через запятую. Виджет ждёт появления элемента до 20 секунд.

События

Заголовок раздела «События»
Событие Когда Данные
search Выполнен поиск { query, search } — параметры и ответ API
completions Пришли подсказки { query, completions }
offer-click Клик по товару { id, url, pos, source, event: { offer } }
item-click Любой отслеживаемый клик: категория, бренд, история, фильтр, «В корзину», избранное { source, … } — тип клика в source, например addToCart
popup-open / popup-close Открыто / закрыто окно поиска (search-popup) —
completions-open / completions-close Открыты / закрыты подсказки —
image-search-open / image-search-close Окно поиска по фото —

На window также приходит событие searchbooster.initialized — когда виджет загружен.

sb.on('item-click', (data) => {
  if (data.source === 'addToCart') ym(XXXXXX, 'reachGoal', 'sb_add_to_cart');
});

Свой код инициализации

Заголовок раздела «Свой код инициализации»

Когда нужны функции (корзина, обработчики), код инициализации пишут на сайте вместо стандартного загрузчика — или его включает поддержка в личном кабинете:

<script>
  (function (w, d) {
    w.searchbooster = w.searchbooster || function () { (w.searchbooster.a = w.searchbooster.a || []).push(arguments); };
    w.searchbooster({
      apiKey: 'PROJECT_UUID',
      regionId: () => w.myShop.regionId,
      offer: { cart: { items: () => w.myShop.cart.items(), onChangeOfferCount: (p) => w.myShop.cart.change(p) } },
      initialized(sb) {
        sb.mount({ widget: 'search-popup', selector: '#search-input' });
      },
    });
    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://cdn2.searchbooster.net/scripts/v3/init.js';
    d.head.appendChild(s);
  })(window, document);
</script>

Используется только последний вызов searchbooster(...) до загрузки скрипта.

Полезные параметры URL

Заголовок раздела «Полезные параметры URL»
Параметр Что делает
?sbdemo=true / ?sbdemo=false Включить / выключить виджет для себя в режиме интеграции.
?no_search=1 Временно отключить виджет на странице — проверить, мешает ли он чему-то.
?searchbooster_disable_tracking=1 Не отправлять аналитику с этого браузера (для тестировщиков).