Частые ошибки

Диагностика типичных проблем установки. Сначала — таблица «симптом → причина → что делать» для быстрого поиска, ниже — разбор случаев, где нужен код.

Быстрый справочник

Симптом	Причина	Что делать
SearchForceWidget is not defined, виджет не появляется	Скрипт не подключился	Проверить в Network, что searchforce-widget.js отдаётся со статусом 200; сверить адрес и projectId; проверить блокировщики и CSP.
init: target not found for selector "…"	В ручном режиме init() вызван раньше появления элемента	Оборачивать вызовы в SearchForceWidget.ready() (ручной режим); проверить селектор/класс. Авто-подключение ждёт DOM само.
Поиск открывается, но по Enter никуда не ведёт	Не задан searchUrl — виджет бросает событие вместо перехода	Указать searchUrl = URL страницы выдачи. Либо осознанно обработать sf:search-submit (см. «События»).
Страница выдачи пустая, запрос не подставляется	Разный searchQueryParam у строки и страницы, или нет контейнера	Один и тот же параметр (q); проверить, что на странице есть #sf-fullpage-root.
Сменили indexName — каталог не поменялся	Каталог определяется projectId, а не indexName	Так и задумано: indexName — только ключ индекса InstantSearch (по умолчанию products) в обоих блоках; менять его не нужно.
Панель подсказок заезжает под шапку	Фиксированная/динамическая шапка	См. ниже.
В Битриксе скрипт переносится / init срабатывает дважды	Оптимизатор Битрикса двигает скрипты	Добавить data-skip-moving (см. ниже).
Карточки выглядят не так (чужой бейдж, не те картинки)	Карточка не подогнана под ваш фид	Поправьте карточку в редакторе виджета; см. ниже.
Поиск не работает, запросы уходят «не туда»	На странице передан неверный apiUrl (переопределил вшитый)	Либо не передавайте apiUrl (используется вшитый при сборке), либо укажите https://platform.searchforce.ru.
История поиска не длиннее 5	История фиксирована на 5 последних запросах	Ожидаемое поведение, не настраивается.
Свои CSS-правила «не подхватываются»	Стили виджета вшиты в JS и грузятся в runtime	Оформлять через токены --sf-*, а не перезаписью классов (см. «Оформление»).

Разбор частых случаев

Виджет не загружается

Признаки: в консоли SearchForceWidget is not defined, поле поиска ведёт себя как обычное, панели нет.

1. Network → searchforce-widget.js — статус должен быть 200 и тип application/javascript. 404 — неверный адрес или projectId в пути.
2. CSP — если на сайте настроен Content-Security-Policy, разрешите platform.searchforce.ru в script-src и connect-src.
3. Блокировщики — расширения-блокировщики иногда режут сторонние скрипты; проверьте в режиме инкогнито без расширений.
4. Порядок (ручной режим) — если инициализируете сами, оборачивайте вызовы в SearchForceWidget.ready(...) (ручной режим), иначе обращение к SearchForceWidget может произойти до загрузки скрипта. При авто-подключении это не нужно.

Поиск открывается, но по Enter никуда не ведёт

Так проявляется незаданный searchUrl. Без него виджет намеренно не делает переход, а бросает событие sf:search-submit. Варианты:

• Нужен обычный переход на страницу выдачи → задайте searchUrl: '/search/' (URL вашей страницы с #sf-fullpage-root).
• Нужна своя логика перехода → оставьте searchUrl пустым и обработайте sf:search-submit.

И проверьте связку: searchQueryParam у строки должен совпадать с параметром, который читает страница выдачи (по умолчанию q). Встроенный виджет fullpage читает только ?q= — если выдачу рисует он, оставьте значение по умолчанию.

Панель заезжает под фиксированную шапку

Виджет позиционирует панель через --sf-ac-offset-top и обновляет значение автоматически. Для нестандартной или динамически меняющейся шапки задайте отступ вручную — например, пересчитывая его при ресайзе по фактической высоте шапки:

var header = document.querySelector('.header');
if (header) {
  var updateOffset = function () {
    var offset = Math.round(header.getBoundingClientRect().bottom) + 'px';
    document.querySelectorAll('.sf-ac-root').forEach(function (el) {
      el.style.setProperty('--sf-ac-offset-top', offset);
    });
  };
  new ResizeObserver(updateOffset).observe(header);
  addEventListener('scroll', updateOffset, { passive: true });
  addEventListener('resize', updateOffset, { passive: true });
  updateOffset();
}

Битрикс двигает или дублирует скрипт

Оптимизатор Битрикса умеет переносить и объединять скрипты, из-за чего порядок загрузки ломается, а инициализация может сработать дважды. Решение:

• Пометьте и скрипт виджета, и блок инициализации атрибутом data-skip-moving — оптимизатор их не тронет (см. рецепт для Битрикса).
• Повторный вызов .init() на том же элементе безопасен: виджет снимает предыдущий экземпляр сам. Для страниц, которые подгружаются через AJAX, используйте dispose() (см. «Повторная инициализация»).

Карточки выглядят не так (чужой бейдж, не те картинки)

Разметка карточки — файл card/ProductCard.vue в редакторе виджета, а её стили — тема theme/tokens.css. Если карточки отображаются неверно (лишний бейдж «Sale», не те изображения или атрибуты), поправьте карточку в редакторе: какие атрибуты показывать, берётся хелпером getAttr(hit, 'Ключ') под ключи вашего фида. После правок нажмите «Сохранить и опубликовать». Если не уверены, что менять, — напишите в поддержку, приложив ссылку на страницу с проблемой.

Куда смотреть при отладке

• Network — searchforce-widget.js (200), запросы POST …/search (200).
• Console — сообщения [SearchForce] и ошибки init: target not found.
• Elements — присутствует ли #sf-fullpage-root на странице выдачи и класс sf-search-trigger на поле поиска.

Если проблему не удалось локализовать — напишите в поддержку, приложив URL страницы и скриншот вкладки Network/Console.