# Квэлп: Умный поиск

Полное руководство qwelp.search. Сверено с установленной справкой 9 сентября 2026 года.

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

## Начало

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

1. Установите модуль в разделе Marketplace → Установленные решения. Нужны модули «Главный модуль», «Информационные блоки» и «Поиск».
2. Откройте Квэлп → Умный поиск → Настройки. Выберите сайт, его инфоблоки и поля поиска; сохраните настройки.
3. Откройте Переиндексация, выберите тот же сайт и выполните индексацию. Подключите компоненты из вкладки «Компоненты» и проверьте известный товар.

Для цен и торговых предложений нужен штатный модуль «Торговый каталог». Другие модули Qwelp необязательны. Внешний поисковый сервис и платная подписка не требуются.

## Настройка

1. В верхней части настроек выберите сайт. Повторите настройку для каждого сайта установки.
2. Укажите инфоблоки и свойства с названиями, артикулами и другими поисковыми данными. После изменения набора данных выполните переиндексацию.
3. Настройте подсказки, исправление запросов и сбор аналитики. Проверьте выдачу под обычным посетителем. Адреса товаров и разделов берутся из настроек инфоблока. Для нестандартного каталога откройте Настройки → Ссылки: задайте шаблон товара и/или раздела для нужного сайта и инфоблока. Пустое поле возвращает настройку инфоблока.

| Раздел | Назначение |
| --- | --- |
| Поиск | Включение модуля, источники и поля, длина запроса, раскладка, морфология и исправление опечаток. |
| Подсказки | Количество категорий, товаров, брендов и популярных запросов; история посетителя. |
| Аналитика | Журнал запросов, переходы, нулевые результаты и сроки хранения. |
| Права | В штатных настройках модуля: D — закрыто, R — чтение отчётов, W — изменение настроек и словарей. |

Общие файлы устанавливаются в /bitrix/modules/qwelp.search/, /bitrix/components/qwelp/search.* и /bitrix/js/qwelp/search/. Второму сайту не нужна собственная копия /local/. Клиентские шаблоны в /local/ сохраняются.

## Компоненты

Для страницы результатов создайте обычную страницу Битрикса, например search/index.php, и разместите вызов между подключениями header.php и footer.php. Для подсказок добавьте второй пример в шаблон шапки или другую область страницы. На странице результатов достаточно первого примера: в нём уже есть форма с живыми подсказками. Не добавляйте второй пример над первым — появятся два поля поиска.

```php
$APPLICATION->IncludeComponent('qwelp:search.page', '.default', [
    'PER_PAGE' => '20',
    'INPUT_NAME' => 'q',
    'PAGER_NAME' => 'qs_page',
    'SUGGEST_TEMPLATE' => '.default',
    'CACHE_TYPE' => 'A',
    'CACHE_TIME' => '36000000',
], false);
```

```php
$APPLICATION->IncludeComponent('qwelp:search.title', '.default', [
    'SHOW_INPUT' => 'Y',
    'INPUT_NAME' => 'q',
    'PAGE' => '#SITE_DIR#search/',
    'NUM_PRODUCTS' => '5',
], false);
```

| Параметр | Значение |
| --- | --- |
| PER_PAGE / PAGER_NAME | Размер страницы 1–100 (20 по умолчанию); параметр пагинации qs_page. |
| INPUT_NAME / SUGGEST_TEMPLATE | Имя поля запроса q; имя шаблона вложенных подсказок .default. |
| SET_TITLE / BREADCRUMB_NAV / SHOW_ZERO_RESULT_SUGGESTIONS | Заголовок, навигационная цепочка и предложения при пустой выдаче: Y/N. |
| PAGE / PLACEHOLDER | Адрес результатов #SITE_DIR#search/ и текст подсказки поля. |
| SHOW_INPUT / FORM_SELECTOR | Y выводит собственную форму; N подключает существующую форму по CSS-селектору. |
| SHOW_POPULAR / SHOW_HISTORY | Популярные запросы и история: Y/N. |
| NUM_CATEGORIES / NUM_PRODUCTS / NUM_BRANDS | Лимиты подсказок: 3 / 5 / 2 по умолчанию. |
| USE_PARENT_FORM | Y предназначен для вложенного вызова из search.page; отдельно оставьте N. |
| CACHE_TYPE / CACHE_TIME | Штатные параметры кеширования Битрикса. Изменение данных сбрасывает кеш результатов. |

Если имя поля отличается от q, задайте одно имя на странице и в форме. PAGER_NAME должен отличаться от INPUT_NAME и qs_exact. Параметры сохраняйте штатным редактором компонентов; в управляемом массиве используйте строки и числа.

## Оформление

1. Скопируйте всю папку .default нужного компонента в папку шаблона сайта по примеру ниже.
2. Измените template.php, style.css, view.js и языковые файлы внутри копии. Сохраните data-атрибуты, ARIA и экранирование.
3. Выберите имя копии в параметрах компонента. Для страницы результатов укажите имя копии подсказок в SUGGEST_TEMPLATE.

```text
/local/templates/<site_template>/components/qwelp/search.title/my_search/
/local/templates/<site_template>/components/qwelp/search.page/my_results/
```

view.js отвечает за разметку AJAX-результатов. Общий search.bundle.js обслуживает запросы, клавиатуру и жизненный цикл. Копируйте весь шаблон вместе с view.js; не изменяйте общие файлы модуля ради дизайна.

:::details Кешируемый родитель и AJAX

Если форма находится в кеше родительского компонента или произвольном HTML-фрагменте, загрузите расширение вне этой кешируемой области. Проверьте холодный и повторный запросы, замену HTML и несколько форм.

:::

```php
\Bitrix\Main\UI\Extension::load('qwelp.search');
```

Для подробного контракта шаблонов см. docs/templates.md в установленном модуле. При обновлении изменённые клиентские файлы не перезаписываются; сообщение о конфликте требует сравнения и переноса собственных изменений.

## Аналитика и словари

1. Откройте Аналитика, выберите сайт и период. Смотрите нулевые запросы и переходы из выдачи.
2. Если нужный товар существует под другим названием, добавьте правило в Синонимы. Для перехода на существующую страницу используйте Редиректы.
3. Используйте Стоп-слова для служебных слов. После изменения правила повторите запрос и проверьте результат.

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

| Настройка | По умолчанию |
| --- | --- |
| LOG_RETENTION_DAYS | Журнал запросов: 90 дней. |
| PII_RETENTION_DAYS | Связанные с посетителем данные: 30 дней. |
| ZERO_RESULT_RETENTION_DAYS / POPULAR_RETENTION_DAYS | Нулевые и популярные запросы: 180 дней. |
| IP_FULL_RETENTION | Полный IP отключён. |
| POPULAR_MIN_HITS / POPULAR_MIN_UNIQUE_ACTORS | Не менее 3 запросов и 3 разных посетителей. |

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

## Проверка и удаление

| Симптом | Что проверить |
| --- | --- |
| Пустая выдача | Сайт, выбранные инфоблоки, активность и права товара, поля поиска и завершение индексации. |
| Нет подсказок | Загрузка расширения qwelp.search, view.js выбранного шаблона, правильный FORM_SELECTOR и ошибки консоли. |
| Старая выдача | Работа агентов, завершение переиндексации и кеш родителя/Композита. |
| Нет аналитики | Включены ли журнал и аналитика; выбран ли правильный сайт и период. GET-подсказка без действия посетителя не записывается как поиск. |
| Конфликт установки | Сравните принадлежащий модулю файл с клиентской копией. Не удаляйте чужие файлы для обхода проверки. |

Перед удалением сделайте резервную копию. В Marketplace → Установленные решения выберите удаление «Квэлп: Умный поиск». Отмеченное «Сохранить данные» сохраняет настройки и таблицы для повторной установки. Снятие отметки подтверждает удаление собственных данных модуля.

Удаление затрагивает общий модуль на обоих сайтах. Уберите вызовы его компонентов из своих страниц. Если операция прервана, повторите её штатно: установщик продолжит сохранённый этап.

Требования: PHP 8.2+, Bitrix main 23.0+, UTF-8, MySQL 8.0+. Для каталога нужны соответствующие модули платформы. На большом каталоге измерьте время и число запросов: подбор опечаток ограничен словарём до 600 кандидатов и не гарантирует исправление любого слова.