Быстрый старт Relavio Search

Relavio Search добавляет на сайт товарный поиск с подсказками, карточками товаров, голосовым вводом, фильтрами и аналитикой кликов. Виджет подключается через один JavaScript-файл и настраивается HTML-атрибутами.

Что умеет виджет

• Поиск товаров по мере ввода запроса.
• Подсказки с историей запросов, категориями и товарами.
• Каталоговый режим с сеткой товаров и пагинацией.
• Каталоговый режим с фильтрами по брендам, категориям, цене и другим атрибутам.
• Голосовой ввод, если браузер поддерживает Web Speech API.
• Отправка событий клика по товару в аналитику Relavio.
• Автоматическое сохранение поисковой сессии через session_id и search_id.

Перед началом

Для установки нужен API-ключ проекта. Его можно взять в личном кабинете Relavio в настройках магазина или проекта.

Перед подключением убедитесь, что:

• товары импортированы в Relavio Search;
• API-ключ активен;
• домен сайта разрешен для использования виджета;
• страницы товаров содержат корректные ссылки, изображения и цены в фиде или API-импорте.

Минимальная установка

Добавьте контейнер виджета в место, где должен отображаться поиск:

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
></div>

Подключите скрипт перед закрывающим тегом </body>:

<script src="https://relavio.su/js/search-widget.js"></script>

После загрузки скрипта виджет сам найдет все элементы с атрибутом data-relavio-search-widget и инициализирует поиск.

Режимы работы

Режим задается атрибутом data-behavior.

Поиск товаров

Режим по умолчанию. Показывает выпадающий список товаров после ввода запроса.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="search"
></div>

В этом режиме виджет отправляет запросы в /api/v1/search, показывает карточки товаров и догружает следующие страницы при прокрутке списка.

Подсказки

Режим для компактной поисковой строки с автодополнением.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="suggests"
></div>

В ответе отображаются блоки:

• история запросов пользователя;
• поисковые подсказки;
• категории;
• товары.

Клик по подсказке подставляет текст в поле поиска и запускает полноценный поиск.

Каталог

Режим для страницы результатов или каталога товаров.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="catalog"
    data-columns="4"
    data-catalog-rows="4"
></div>

Виджет показывает поле поиска, сетку товаров и постраничную навигацию. Количество товаров на странице рассчитывается из data-columns и data-catalog-rows, если data-per-page не задан явно.

Каталог с фильтрами

Используйте этот режим, если нужно показать фильтры рядом с результатами.

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="catalog-with-filters"
    data-columns="3"
    data-catalog-rows="4"
></div>

Виджет запрашивает результаты с параметром withFilters и строит фильтры из ответа API. Поддерживаются:

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

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

Атрибут	По умолчанию	Описание
data-api-key	пусто	API-ключ проекта Relavio. Обязателен для боевого режима.
data-behavior	search	Режим: search, suggests, catalog, catalog-with-filters.
data-placeholder	Поиск товаров	Текст внутри поля поиска.
data-min-length	2	Минимальная длина запроса для обычного поиска.
data-per-page	8	Количество товаров в ответе. В каталоге может рассчитываться автоматически.
data-columns	4	Количество колонок в каталожной сетке.
data-catalog-rows	4	Количество рядов в каталоге.
data-currency	₽	Валюта для отображения цен, если она не пришла у товара.
data-disable-product-links	false	Отключает переходы по ссылкам товаров.
data-speech-language	ru-RU	Язык голосового ввода.

Пример для поисковой строки в шапке

<div class="header-search">
    <div
        data-relavio-search-widget
        data-api-key="YOUR_API_KEY"
        data-behavior="suggests"
        data-placeholder="Найти товар"
    ></div>
</div>

<script src="https://your-relavio-domain.example/js/search-widget.js"></script>

Такой вариант подходит для шапки сайта: пользователь видит подсказки, категории и товары, а при выборе подсказки виджет запускает поиск.

Пример для страницы каталога

<main>
    <h1>Поиск по каталогу</h1>

    <div
        data-relavio-search-widget
        data-api-key="YOUR_API_KEY"
        data-behavior="catalog-with-filters"
        data-placeholder="Введите название товара"
        data-columns="4"
        data-catalog-rows="5"
    ></div>
</main>

<script src="https://relavio.su/js/search-widget.js"></script>

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

Инициализация вручную

Обычно ручная инициализация не нужна. Если контейнер добавляется на страницу динамически, вызовите RelavioSearchWidget.init после вставки элемента в DOM:

<script>
    const element = document.querySelector('[data-relavio-search-widget]');

    window.RelavioSearchWidget.init(element, {
        apiKey: 'YOUR_API_KEY',
        behavior: 'catalog',
        columns: 4,
    });
</script>

Также можно повторно инициализировать все еще не подключенные контейнеры:

<script>
    window.RelavioSearchWidget.initAll();
</script>

Проверка установки

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

• поле поиска появилось на странице;
• при вводе запроса открывается список подсказок или товаров;
• карточки товаров содержат название, изображение, цену и ссылку;
• в каталожном режиме работает пагинация;
• в режиме catalog-with-filters отображаются и применяются фильтры;
• при клике по товару запрос аналитики уходит в /api/v1/search/events.

Если виджет не показывает данные, проверьте API-ключ, наличие товаров в индексе, сетевые ошибки в браузере и доступность эндпоинтов /api/v1/search и /api/v1/search/suggests.

Следующие шаги

• Настройте импорт товаров в разделе search/imports.
• Подберите режим виджета для нужной страницы.
• Настройте внешний вид через CSS-классы relavio-search-widget__*.
• Проверьте аналитику поисковых запросов и кликов после первых пользовательских сессий.