JavaScript-интеграция

Relavio Search можно подключить двумя способами: готовым JavaScript-виджетом или прямыми запросами к API из собственного интерфейса. Отдельный npm SDK пока не требуется: виджет и REST API покрывают основные сценарии интеграции.

Готовый виджет

Самый быстрый способ подключить поиск - вставить контейнер и скрипт.

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

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

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

Режимы виджета

Режим	Описание
search	Быстрый поиск с товарами в выпадающем списке.
suggests	Подсказки, история, категории и товары.
catalog	Каталоговая сетка с пагинацией.
catalog-with-filters	Каталоговая сетка с фильтрами.

Пример каталога с фильтрами:

<div
    data-relavio-search-widget
    data-api-key="YOUR_API_KEY"
    data-behavior="catalog-with-filters"
    data-placeholder="Найти товар"
    data-columns="4"
    data-catalog-rows="4"
></div>

Ручная инициализация

Если контейнер появляется динамически, используйте window.RelavioSearchWidget.init.

<div id="relavio-search"></div>

<script src="https://relavio.su/js/search-widget.js"></script>
<script>
    window.RelavioSearchWidget.init(document.getElementById('relavio-search'), {
        apiKey: 'YOUR_API_KEY',
        behavior: 'catalog',
        placeholder: 'Поиск по каталогу',
        columns: 4,
    });
</script>

Для повторной инициализации всех еще не подключенных контейнеров используйте:

window.RelavioSearchWidget.initAll();

Возвращаемый объект

init возвращает объект с основными DOM-элементами и методами.

const widget = window.RelavioSearchWidget.init(element, {
    apiKey: 'YOUR_API_KEY',
});

widget.input;
widget.dropdown;
widget.catalog;
widget.voiceButton;
widget.search('iphone');
widget.suggests('iph');

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

Прямой запрос к Search API

Если вы строите собственный интерфейс, можно работать с API напрямую.

async function searchProducts(query) {
    const response = await fetch('https://relavio.su/api/v1/search', {
        method: 'POST',
        credentials: 'include',
        headers: {
            Accept: 'application/json',
            'Content-Type': 'application/json',
            'api-key': 'YOUR_API_KEY',
        },
        body: JSON.stringify({
            query,
            page: 1,
            per_page: 20,
            withFilters: true,
        }),
    });

    if (!response.ok) {
        throw new Error(`Relavio Search failed: ${response.status}`);
    }

    return response.json();
}

Подсказки

async function loadSuggests(query, sessionId = '') {
    const response = await fetch('https://relavio.su/api/v1/search/suggests', {
        method: 'POST',
        credentials: 'include',
        headers: {
            Accept: 'application/json',
            'Content-Type': 'application/json',
            'api-key': 'YOUR_API_KEY',
        },
        body: JSON.stringify({
            query,
            session_id: sessionId,
        }),
    });

    return response.json();
}

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

Виджет сам отправляет событие click при клике по товару. Если вы делаете собственный интерфейс, отправляйте события вручную.

async function trackClick(product, searchId, sessionId) {
    await fetch('https://relavio.su/api/v1/search/events', {
        method: 'POST',
        credentials: 'include',
        keepalive: true,
        headers: {
            Accept: 'application/json',
            'Content-Type': 'application/json',
            'api-key': 'YOUR_API_KEY',
        },
        body: JSON.stringify({
            event_id: crypto.randomUUID(),
            event_type: 'click',
            search_id: searchId,
            session_id: sessionId,
            external_id: product.id,
            product_name: product.title,
            position: product.position,
            price: product.price,
            currency: product.currency,
            metadata: {
                url: product.url,
                list: 'custom-search',
            },
        }),
    });
}

Рекомендации

• Используйте готовый виджет, если не нужен полностью кастомный интерфейс.
• Используйте API напрямую, если поиск должен быть частью собственного frontend-приложения.
• Передавайте credentials: 'include', чтобы браузер сохранял поисковую сессию.
• Сохраняйте search_id и session_id из ответов, чтобы связывать клики с запросами.
• Обрабатывайте ошибки 401, 402 и 422 отдельно.

Связанные разделы

• Установка виджета
• Конфигурация виджета
• Search API
• Analytics API