1C-Bitrix: установка и настройка

Пошаговое руководство по установке модуля AACsearch в 1C-Bitrix self-hosted и синхронизации каталога товаров.

Модуль AACsearch для Bitrix интегрирует ваш каталог товаров с облачным поиском. После установки товары синхронизируются автоматически, и виджет поиска появляется на витрине.

Важно: данный модуль работает с self-hosted версией Bitrix (on-premise). Bitrix24 облачная версия требует отдельной интеграции.

Требования

1C-Bitrix 24+ (self-hosted)
PHP 7.4 или выше
Модуль catalog Bitrix включён
Аккаунт на AACsearch и созданный индекс товаров

Установка модуля

Шаг 1. Скачайте модуль

Модуль находится в GitHub репозитории AACsearch.

git clone https://github.com/aacsearch/bitrix-module.git
cd bitrix-module

Шаг 2. Загрузите на сервер Bitrix

Скопируйте папку aac.search в /local/modules/aac.search/ на вашем сервере Bitrix
Или используйте SSH/SFTP для загрузки

scp -r aac.search user@your-bitrix-server:/var/www/bitrix/local/modules/

Шаг 3. Установите модуль

Откройте админ-панель Bitrix
Перейдите в Администрирование → Marketplace → Все модули
Найдите aac.search в списке неустановленных
Нажмите Установить

Или если видите aac.search как не активный модуль:

Перейдите в Администрирование → Модули → Список модулей
Найдите aac.search
Нажмите Активировать

Подключение и настройка

Откройте страницу настроек

В админ-панели Bitrix перейдите в Администрирование → Модули и компоненты → aac.search → Настройки

Заполните основные поля

Поле	Что вводить
URL панели AACsearch	`https://app.aacsearch.com` (или ваш региональный узел)
ID организации	Найдите в панели AACsearch → Настройки → API
Ключ интеграции	Найдите в панели AACsearch → Поиск → Подключения → Новое подключение

Выберите каталог товаров

В поле Каталог / iBlock выберите iblock(ы), которые содержат товары для поиска. Обычно это основной каталог товаров.

Вы можете выбрать несколько iblock-ов, и товары из всех будут синхронизироваться.

Дополнительные параметры

Поле	Описание
Включить синхронизацию	Если отмечено, товары обновляются автоматически
Включить виджет	Если отмечено, виджет поиска встраивается на витрину
Тип цены	Какую цену Bitrix использовать (обычно основная цена)
Валюта	Код валюты (например, RUB)
Язык	Язык товаров (например, Русский)
Интервал синхронизации	Как часто проверять изменения (в минутах, обычно 5–15 мин)
Режим отладки	Если включить, детальные логи пишутся в логи Bitrix

Проверка подключения

Нажмите кнопку Проверить соединение. Модуль отправит тестовый запрос.

Успешное подключение: зелёная галочка и название вашего индекса.

Ошибка: проверьте:

✓ Ключ интеграции скопирован без пробелов
✓ ID организации правильный
✓ На сервере есть доступ в интернет
✓ Firewall не блокирует HTTPS-запросы

Первая синхронизация товаров

Запустите полную синхронизацию

Нажмите кнопку Полная синхронизация каталога. Модуль:

Прочитает все товары из выбранного каталога
Отправит их на серверы AACsearch пакетами
Товары встанут в очередь на индексирование

Сколько это займёт?

100–500 товаров: < 1 минуты
500–5000 товаров: 2–5 минут
5000+ товаров: 10–30 минут

Следите за статусом

На странице Диагностика вы видите:

✅ Сколько товаров успешно загружено
⚠️ Ошибки (если есть)
🔄 Время последней синхронизации

Что синхронизируется

Модуль отправляет:

Название товара (NAME)
Описание (DETAIL_TEXT)
SKU / артикул
Цена — выбранный тип цены из Bitrix
Изображение — основное изображение товара
URL товара — ссылка на карточку товара
Статус наличия — в наличии / нет
Остаток — количество на складе
Свойства (Properties) — размер, цвет и т.д., если настроены

Автоматическое обновление товаров

Если Включить синхронизацию отмечено, модуль автоматически обновляет товары через:

✅ Обработчики событий iblock — срабатывают мгновенно при изменении товара
✅ Агент синхронизации Bitrix — периодически проверяет изменения (интервал в настройках)

Товар синхронизируется когда:

Создан новый товар
Изменена цена
Обновлено название
Изменен остаток
Удален товар

Встраивание виджета поиска

Способ 1: Автоматическое встраивание (рекомендуется)

Если в настройках отмечено Включить виджет, модуль автоматически встраивает код во все страницы вашей витрины через шаблоны Bitrix.

Ничего больше не нужно делать.

Способ 2: Компонент Bitrix

Если вы используете компоненты Bitrix, добавьте компонент в шаблон:

<?php $APPLICATION->IncludeComponent(
    "aac.search:widget",
    "",
    array()
); ?>

Способ 3: Ручное встраивание

Если нужно встроить в конкретное место, скопируйте сниппет из настроек модуля и вставьте в HTML-шаблон вашей темы (обычно в header.php):

<div id="aac-search"></div>
<script 
  src="https://app.aacsearch.com/api/widget/widget.js"
  data-base-url="https://app.aacsearch.com"
  data-api-key="ss_search_***"
  data-index-slug="products"
  data-container="#aac-search">
</script>

Проверка на сайте

Откройте витрину в браузере
Найдите виджет поиска
Введите название товара
Проверьте:
- Появляются ли результаты?
- Видны ли изображения и цены?
- Работают ли фильтры?

Параметры виджета

Вы можете изменить внешний вид через атрибуты data-*:

Параметр	Описание
`data-container`	Селектор контейнера для виджета (например, `#aac-search`)
`data-theme`	`auto` (светлая/тёмная), `light` или `dark`
`data-locale`	Язык: `ru`, `en`, `de`, `es`, `fr`
`data-placeholder`	Текст в поле ввода

Q: Синхронизация занимает долго для 10000+ товаров
A: Это нормально. Bitrix нужно время на чтение товаров и отправку на наши серверы. Вы можете отключить Включить синхронизацию во время первой синхронизации для скорости.

Q: Товары не появляются в поиске
A: Проверьте:

На странице Диагностика все товары показаны как загруженные?
Прошло ли минимум 1–2 минуты с момента загрузки?
В панели AACsearch → Поиск → Синхронизация видны загруженные товары?

Q: При синхронизации ошибка "Ключ не валиден"
A: Создайте новое подключение в панели AACsearch и скопируйте ключ ещё раз.

Q: Виджет не видна на сайте
A: Проверьте:

Включить виджет отмечено в настройках?
Контейнер <div id="aac-search"></div> есть в шаблоне?
В браузере нет ошибок в консоли (F12)?

Q: Как исключить товары из поиска?
A: Создайте отдельный индекс, или используйте фильтры в панели AACsearch для скрытия товаров (например, только товары с ценой > 0, или только активные).

Q: Может ли модуль работать с несколькими витринами на одном Bitrix?
A: Да, если у вас несколько iblock-ов. Выберите их все в Каталог / iBlock, и товары из всех синхронизируются в один индекс.