Подбор товаров по совместимости

Модуль помогает покупателю найти товары, которые подходят к его технике. Вы строите дерево «Марка — Модель — Модификация» и привязываете к нему товары. Посетитель выбирает свою модель над каталогом и видит только подходящие товары, а в карточке товара — список моделей, к которым товар подходит.

Marketplace > Установленные решения > «Подбор товаров по совместимости» > Установить. Нужен модуль «Информационные блоки». Модуль «Торговый каталог» не обязателен; если он установлен, привязки торговых предложений автоматически переносятся на их товары. После установки в админке появится раздел «Контент > Подбор по совместимости» с пунктами «Дерево совместимости», «Привязки товаров», «Импорт из CSV» и «Настройки».

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

Права доступа — вкладка «Доступ» в настройках модуля:

• «Доступ закрыт» — раздел модуля в админке не виден;
  
• «Чтение» — просмотр дерева, привязок и настроек, экспорт CSV;
  
• «Запись» — всё остальное: изменение дерева и привязок, импорт, настройки, сервисные кнопки.
  

Кнопки «Создать демо-данные» и «Удалить демо-данные» дополнительно требуют права записи в модуле «Информационные блоки» (или прав администратора): демо-данные — это отдельный инфоблок. Права на модуль действуют и для методов REST.

Чтобы посмотреть подбор до загрузки своих данных:

1. Откройте «Настройки» модуля и нажмите «Создать демо-данные». Появятся инфоблок «Автозапчасти (демо)» с товарами и свойством «Артикул» (ARTNUMBER) и пять марок автомобилей с моделями, модификациями и годами выпуска; товары уже привязаны. Если инфоблок каталога в настройках не выбран, выбирается демо-инфоблок.
   
2. Создайте страницу и разместите на ней подбор и список товаров демо-инфоблока — код в разделе 7 и на вкладке «Подключение» в настройках.
   
3. У демо-инфоблока нет детальных страниц: чтобы открыть карточку товара, задайте в настройках инфоблока «URL страницы детального просмотра» вне папки подбора и создайте для неё страницу с bitrix:catalog.element и компонентом «Применимость товара» (раздел 10).
   
4. Когда загрузите свои данные, нажмите «Удалить демо-данные». Удаляются демо-марки со всем вложенным и демо-инфоблок со всеми элементами, в том числе добавленными вами вручную. Ваши товары и марки не затрагиваются. Марки, которые уже были в дереве до создания демо-данных, демо-данные не дублируют.
   

«Контент > Подбор по совместимости > Настройки». На вкладке «Подключение» — готовый код всех компонентов.

Дерево совместимости

• Названия уровней дерева — по одному на строку, сверху вниз: «Марка», «Модель», «Модификация» или «Производитель», «Серия», «Модель принтера». Пусто — «Марка», «Модель», «Модификация». Уровней может быть до 10.
  

Импорт из CSV

• Инфоблок каталога — в нём импорт ищет товары. Обязателен, если товары ищутся не по ID.
  
• Колонка PRODUCT файла содержит — ID товара, внешний код (XML_ID), символьный код или значение свойства.
  
• Символьный код свойства — для поиска по значению свойства, например ARTNUMBER (артикул).
  
• Демо-данные — см. раздел 2.
  

Публичная часть

• Помнить выбор посетителя, дней — сколько хранить выбранную модель в cookie (до 365). 0 — только до конца сеанса.
  
• Моделей в «Моём гараже» — сколько моделей может сохранить покупатель (1–50). При сохранении сверх лимита удаляются самые старые.
  

Большие каталоги — см. раздел 13. Страницы подбора и SEO — раздел 8. Автоимпорт — раздел 12.

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

«Дерево совместимости»: создайте марки, внутри них модели, внутри моделей модификации. Щелчок по названию открывает следующий уровень. Правило подбора: товар, привязанный к модели, подходит ко всем её модификациям; посетитель, выбравший только марку, видит товары ко всем её моделям.

На странице элемента дерева:

• Активность — неактивный элемент скрыт от посетителей вместе со всем вложенным.
  
• Символьный код — латиница, цифры, «_» и «-»; из кодов строятся адреса страниц подбора (/podbor/toyota/camry/). Если в настройках включено «Заполнять символьный код из названия», код подставляется сам при вводе названия; очищенный код при сохранении заполняется заново.
  
• Годы выпуска — с какого и по какой год. Можно указать только начало или только конец. Посетитель видит годы рядом с названием, по ним работает выбор «Год выпуска» в подборе.
  
• Показывать на сайтах — появляется, если сайтов несколько (раздел 14).
  
• Синонимы названия — другие написания, по одному на строку, например «VW» для «Volkswagen». Импорт найдёт элемент по любому из них.
  
• Вкладка «Описание» — картинка (логотип марки или фото модели: JPG, PNG, GIF или WEBP, до 5 МБ) и текст для страницы подбора. В тексте можно использовать HTML: небезопасные теги и атрибуты при выводе убираются.
  
• Вкладка «SEO» — заголовок H1, title и description страницы подбора этого элемента. Пустые поля заполняются по шаблонам из настроек.
  
• Перемещение и объединение — блок под формой. «Переместить» переносит элемент со всем вложенным в другое место дерева. «Объединить» соединяет дубли, например «VW» и «Volkswagen»: привязки переходят к выбранному элементу, вложенные элементы с одинаковыми названиями тоже объединяются, исходный элемент удаляется, а его название становится синонимом. Годы, картинка и описание переходят, если у выбранного их нет. Отменить объединение и перемещение нельзя.
  

Удаление элемента удаляет всё вложенное и привязки к нему.

• «Привязки товаров» — список всех привязок с фильтром по элементу дерева и товару. На вкладке «Привязать товары» выберите элемент дерева выпадающими списками по уровням, товары — кнопкой «Выбрать товары…» или списком ID через запятую, пробел или с новой строки, и при необходимости примечание, позицию установки («передняя левая») и количество на автомобиль.
  
• Карточка товара в админке — вкладка «Применимость»: к чему привязан товар, добавление и удаление привязок. Изменения на вкладке сохраняются сразу, без сохранения товара. Вкладка есть у товаров инфоблока, выбранного в настройках, а если он не выбран — у всех инфоблоков торгового каталога.
  
• Привязывайте сами товары: ID торгового предложения при привязке заменяется ID его товара.
  
• При удалении товара его привязки удаляются автоматически.
  

«Импорт из CSV». Первая строка файла — названия колонок:

PRODUCT;LEVEL1;LEVEL2;LEVEL3;NOTE;POSITION;QUANTITY;YEAR_FROM;YEAR_TO
OF-123;Toyota;Camry;XV70 2.5;;;1;2017;2021
BR-77;Toyota;Camry;;;передняя ось;2;;

• PRODUCT — товар: ID, внешний код, символьный код или значение свойства, как указано в настройках.
  
• LEVEL1, LEVEL2… — путь в дереве. Если заполнены не все уровни, товар привязывается к последнему заполненному: во второй строке примера — ко всей модели Camry.
  
• Необязательные: NOTE — примечание, POSITION — позиция установки, QUANTITY — количество, YEAR_FROM и YEAR_TO — годы выпуска последнего заполненного уровня.
  
• Недостающие элементы дерева создаются сами. Названия сравниваются без учёта регистра и с учётом синонимов: строки с «VW» попадут в «Volkswagen», если у него указан синоним «VW».
  
• Если привязка уже есть, заполненные в файле примечание, позиция и количество заменяют прежние, пустые ячейки ничего не меняют. Так же с годами выпуска.
  
• Режим «Добавить» дописывает новые привязки. Режим «Заменить» сначала удаляет прежние привязки товаров из файла.
  
• Разделитель — точка с запятой, запятая или табуляция; кодировка — UTF-8 или windows-1251.
  

Большие файлы импортируются по частям с индикатором хода. Если закрыть страницу, импорт продолжится с того же места при следующем открытии. Кнопка «Остановить импорт» прерывает его, уже добавленные привязки сохраняются. После импорта показываются итоги: сколько строк обработано, сколько привязок добавлено и сколько уже было, сколько элементов дерева создано, и строки с ошибками с номерами (например, «товар не найден»).

Экспорт — на той же странице: вся таблица применимости в CSV в формате импорта. Файл можно поправить в Excel и загрузить обратно. Пример файла — docs/example.csv в папке модуля.

Разместите компонент «Подбор по совместимости» (xlogic:compatibility.picker) перед компонентом каталога и укажите им одно и то же имя переменной фильтра:

<?$APPLICATION->IncludeComponent("xlogic:compatibility.picker", "", [
   "FILTER_NAME" => "arrFilter",
   "REMEMBER_CHOICE" => "Y",
   "SHOW_GARAGE" => "Y",
   "SHOW_YEAR" => "Y",
   "SHOW_NODE_INFO" => "Y",
]);?>

• У bitrix:catalog.section достаточно того же FILTER_NAME.
  
• У комплексного bitrix:catalog дополнительно должен быть включён «Показывать фильтр» (USE_FILTER). Подбор работает на страницах разделов; главная страница комплексного каталога переменную фильтра не учитывает — для страницы со всеми товарами используйте bitrix:catalog.section с параметром «Показывать элементы всех разделов».
  
• Умный фильтр, сортировка и постраничная навигация работают вместе с подбором.
  

Параметры компонента:

• REMEMBER_CHOICE — запоминать выбор посетителя (срок — в настройках модуля).
  
• SHOW_GARAGE — показывать «Мой гараж» авторизованным посетителям.
  
• SHOW_YEAR — список «Год выпуска», если у элементов дерева указаны годы. После выбора года в уровнях остаются модели и модификации, которые выпускались в этом году (элементы без годов остаются всегда). Год сужает выбор модели, но не список товаров: товары, привязанные ко всей модели, показываются при любом годе.
  
• SHOW_NODE_INFO — картинка, годы и описание выбранной модели под подбором.
  
• SEF_MODE, SEF_FOLDER, SET_TITLE, ADD_CHAIN_ITEM — для страниц подбора с ЧПУ (раздел 8).
  

Уровни подгружаются без перезагрузки страницы; список товаров обновляется, когда выбран последний уровень, или по кнопке «Подобрать» — например, чтобы показать товары ко всей марке. Ссылка «Сбросить» снимает выбор. Внешний вид меняется копированием шаблона компонента в шаблон сайта.

Отдельная страница под каждую модель с адресом вида /podbor/toyota/camry/, своим заголовком, title и description:

1. В настройках модуля, раздел «Страницы подбора и SEO», укажите «Папку страниц подбора», например /podbor/, и сохраните — модуль добавит правило обработки адресов. Если сайтов несколько, папка и адрес для sitemap задаются для каждого сайта в таблице «Свои значения для сайтов»; папку указывайте от корня сайта с учётом его каталога, например /en/podbor/.
   
2. Включите «Заполнять символьный код из названия» и нажмите «Заполнить пустые коды»: адреса строятся из символьных кодов элементов дерева.
   
3. Создайте страницу /podbor/index.php с подбором и списком товаров:
   

<?$APPLICATION->IncludeComponent("xlogic:compatibility.picker", "", [
   "FILTER_NAME" => "arrFilter",
   "SEF_MODE" => "Y",
   "SEF_FOLDER" => "/podbor/",
   "SET_TITLE" => "Y",
   "ADD_CHAIN_ITEM" => "Y",
]);?>
<?$APPLICATION->IncludeComponent("bitrix:catalog.section", "", [
   "IBLOCK_ID" => IBLOCK_ID_CATALOG,
   "FILTER_NAME" => "arrFilter",
   "SHOW_ALL_WO_SECTION" => "Y",
   "SET_TITLE" => "N",
   "SET_BROWSER_TITLE" => "N",
   "SET_META_DESCRIPTION" => "N",
   ...
]);?>

• В окне настроек компонента подбора это «Включить поддержку ЧПУ» и «Каталог ЧПУ». Именно эти параметры сохраняют правило обработки адресов, когда страницу правят в визуальном редакторе.
  
• У списка товаров выключите установку заголовка и мета-тегов, иначе он перезапишет заголовки страниц подбора. Не используйте на этой странице комплексный bitrix:catalog и не включайте режим ЧПУ у catalog.section — они перехватывают адреса подбора.
  
• Папка подбора целиком принадлежит подбору: любой адрес внутри неё он разбирает как марку и модель. Детальные страницы товаров должны лежать в другом месте — например, в обычном каталоге сайта. Проверьте «URL страницы детального просмотра» в настройках инфоблока: он не должен начинаться с папки подбора.
  
• Заголовок H1, title и description берутся с вкладки «SEO» элемента дерева, а если там пусто — из шаблонов в настройках. Макросы: #NAME# — название выбранного элемента, #CHAIN# — вся цепочка («Toyota Camry XV70»), #LEVEL# — название уровня. По умолчанию: «Товары для #CHAIN#».
  
• Выбранная модель добавляется в навигационную цепочку («Подбор — Toyota — Camry»). Несуществующий адрес отдаёт ответ 404.
  
• Выбор в форме подбора и ссылки «Моего гаража» переводят на адрес страницы модели; параметры сортировки и другие параметры страницы сохраняются.
  

Sitemap. Укажите «Адрес сайта для sitemap» (например, https://example.ru) и включите «Обновлять sitemap страниц подбора»: файл sitemap_xlogic_compatibility.xml в корне сайта (при нескольких сайтах — sitemap_xlogic_compatibility_<ID сайта>.xml) обновляется агентом раз в сутки, кнопка «Сформировать сейчас» — сразу. В файл попадают только видимые элементы с заполненными кодами. Добавьте его в robots.txt строкой «Sitemap: адрес сайта/sitemap_xlogic_compatibility.xml».

Авторизованный покупатель сохраняет свои модели и переключается между ними одним щелчком. Компонент подбора показывает гараж над каталогом (параметр SHOW_GARAGE). Для шапки сайта, личного кабинета и других страниц без подбора есть отдельный компонент «Мой гараж»:

<?$APPLICATION->IncludeComponent("xlogic:compatibility.garage", "", [
   "CATALOG_URL" => "#SITE_DIR#catalog/",
   "AUTH_URL" => "#SITE_DIR#auth/",
   "SHOW_CURRENT" => "Y",
   "SHOW_GUEST_HINT" => "Y",
]);?>

• CATALOG_URL — страница каталога с подбором. Ссылки на модели ведут на страницы подбора с ЧПУ, если они настроены, иначе — на эту страницу с выбранной моделью. Укажите реальный адрес каталога вашего сайта.
  
• SHOW_CURRENT — показывать модель, выбранную сейчас, и кнопку «Сохранить в гараж».
  
• SHOW_GUEST_HINT и AUTH_URL — гостям предлагается войти, со ссылкой на страницу входа.
  

Блок персональный: в композитном режиме он выводится динамической областью.

Компонент «Применимость товара» выводит модели, к которым подходит товар, с годами выпуска, позицией установки, количеством и примечанием; каждая модель — ссылка на подбор. В template.php шаблона компонента bitrix:catalog.element в шаблоне сайта, в нужном месте карточки:

<?$APPLICATION->IncludeComponent("xlogic:compatibility.product", "", [
   "PRODUCT_ID" => $arResult["ID"],
   "CATALOG_URL" => $arResult["LIST_PAGE_URL"],
   "LIMIT" => 500,
], $component);?>

• CATALOG_URL — страница каталога с подбором, для ссылок, если страницы подбора с ЧПУ не настроены.
  
• LIMIT — сколько моделей показывать, не больше 2000.
  
• У товара без привязок блок не выводится. Кеш сбрасывается сам при изменении дерева или привязок, если на сайте включено управляемое кеширование.
  

Отметка зависит от выбора посетителя, поэтому ставится в браузере одним запросом на всю страницу: кеш и композитный режим не нарушаются.

1. В header.php шаблона сайта:

   <?php if (\Bitrix\Main\Loader::includeModule("xlogic.compatibility")) {    CJSCore::Init(["xlogic_compatibility_fits"]); } ?>

   
   
2. В шаблонах bitrix:catalog.section (у каждого товара) и bitrix:catalog.element добавьте атрибут с ID товара и место для отметки:

   <div data-xcompat-product="<?= (int) $item["ID"] ?>">    ...    <span data-xcompat-badge hidden></span> </div>

   
   

Если модель выбрана, блок товара получает класс xcompat-fits--yes или xcompat-fits--no, а отметка — текст «Подходит к …» или «Не подходит к …». Товары, подгруженные кнопкой «Показать ещё», проверяются автоматически.

Настройки модуля, раздел «Автоимпорт»:

• Файл таблицы применимости — адрес выгрузки поставщика (http или https, порт 80 или 443) или путь к файлу в папке обмена /upload/xlogic.compatibility/, например /upload/xlogic.compatibility/table.csv. Файлы из других папок сайта не принимаются. Адреса внутренней сети и самого сервера модуль не скачивает, в том числе после переадресации, — такой запуск завершится ошибкой «Адрес файла недоступен».
  
• Запускать раз в, часов — 0 выключает автоимпорт.
  
• Режим — «Добавить новые привязки» или «Заменить привязки товаров из файла».
  
• E-mail для отчёта об ошибках — письмо (почтовое событие XLOGIC_COMPAT_IMPORT_REPORT) приходит, если файл не скачался или в строках есть ошибки. Шаблон письма меняется в настройках почтовых событий.
  

Формат файла — как у импорта из CSV, размер — до 200 МБ. Импорт выполняется агентом по частям; файл, который не изменился с прошлого раза, пропускается. Каждый запуск записывается в журнал «Последние запуски» с итогами и ошибками. Кнопка «Запустить сейчас» запускает импорт сразу, даже если файл не изменился (сначала сохраните настройки). Агенты лучше перевести на cron, иначе импорт идёт только при посещениях сайта.

По умолчанию подбор передаёт каталогу список ID подходящих товаров. Для каталогов от нескольких тысяч товаров включите «Фильтровать каталог по служебному свойству» (раздел «Большие каталоги») и сохраните настройки:

• модуль создаст в инфоблоке каталога служебное множественное свойство XLOGIC_COMPAT_FIT и заполнит его агентом; ход заполнения в процентах виден в настройках;
  
• пока свойство заполняется, подбор работает по списку ID, поэтому посетитель не увидит неполный результат;
  
• после заполнения подбор передаёт каталогу условие по свойству: запрос остаётся лёгким, работает фасетный индекс;
  
• изменения привязок вручную и на вкладке «Применимость» записываются в свойство сразу, после импорта и крупных изменений дерева свойство перестраивается агентом;
  
• свойство не редактируйте вручную и не выводите в умный фильтр. Если оно разошлось с привязками, нажмите «Перестроить».
  

• На странице элемента дерева отметьте «Показывать на сайтах»; ничего не отмечено — на всех. Скрытый на сайте элемент скрывает всё вложенное: в подборе, на страницах с ЧПУ, в sitemap, в гараже и в применимости карточки.
  
• Папка страниц подбора и адрес для sitemap задаются для каждого сайта в таблице «Свои значения для сайтов»; у каждого сайта свой файл sitemap.
  

События модуля xlogic.compatibility: OnBeforeLinkAdd, OnAfterLinkAdd, OnAfterLinkUpdate, OnBeforeLinkDelete, OnAfterLinkDelete, OnBeforeNodeAdd, OnAfterNodeAdd, OnBeforeNodeUpdate, OnAfterNodeUpdate, OnBeforeNodeDelete, OnAfterNodeDelete, OnAfterNodeMove, OnAfterNodeMerge. Обработчик события OnBefore может отменить действие:

\Bitrix\Main\EventManager::getInstance()->addEventHandler("xlogic.compatibility", "OnBeforeLinkAdd", function (\Bitrix\Main\Event $event) {
   $fields = $event->getParameters(); // PRODUCT_ID, NODE_ID, NOTE, POSITION, QUANTITY
   if ($fields["QUANTITY"] > 10) {
      return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::ERROR, ["message" => "Too many"], "xlogic.compatibility");
   }
});

При удалении элемента дерева привязки его поддерева удаляются без событий привязок — приходит одно событие OnAfterNodeDelete.

REST (нужен модуль REST), область xlogic_compatibility:

• xlogic.compatibility.tree.children (parent_id) — дочерние элементы, 0 — верхний уровень;
  
• xlogic.compatibility.node.get (id) — элемент с цепочкой предков;
  
• xlogic.compatibility.product.links (product_id) — к чему привязан товар;
  
• xlogic.compatibility.finder.products (node_id, start) — ID подходящих товаров, по 500;
  
• xlogic.compatibility.link.add (product_id, node_id, note, position, quantity) и xlogic.compatibility.link.delete (id) — изменение привязок.
  

Пользователю вебхука или приложения нужны права на модуль: «Чтение» для чтения, «Запись» для изменения привязок.

Из PHP, например в своём шаблоне: \Xlogic\Compatibility\Service\LinkService::getProductFitment($productId) — применимость товара (то же, что выводит компонент «Применимость товара»); \Xlogic\Compatibility\Service\Selection::getNodeId() — модель, выбранная посетителем; \Xlogic\Compatibility\Service\Selection::filterCompatible($productIds) — какие из товаров к ней подходят. Перед вызовом подключите модуль: \Bitrix\Main\Loader::includeModule("xlogic.compatibility").

• Подбор выбран, а список товаров не сужается. Проверьте, что у подбора и у компонента каталога одинаковый FILTER_NAME и подбор стоит на странице выше каталога. У комплексного bitrix:catalog должен быть включён «Показывать фильтр», а на его главной странице фильтр не работает — используйте bitrix:catalog.section.
  
• Страницы /podbor/toyota/… открываются пустыми или с ошибкой 404 у всех моделей. Проверьте, что в «Настройки > Настройки продукта > Обработка адресов» есть правило для папки подбора; если нет — откройте настройки модуля и нажмите «Сохранить». Проверьте, что у подбора на странице указаны SEF_MODE и SEF_FOLDER (иначе правило может пропасть при правке страницы в визуальном редакторе) и что веб-сервер передаёт несуществующие адреса в /bitrix/urlrewrite.php.
  
• Заголовок страницы подбора не меняется. У списка товаров на этой странице выключите установку заголовка и мета-тегов (SET_TITLE, SET_BROWSER_TITLE, SET_META_DESCRIPTION).
  
• Со страницы подбора не открывается карточка товара (404 или снова подбор). Адрес детальной страницы товара попал в папку подбора, например /podbor/#ELEMENT_CODE#/. Перенесите детальные страницы в каталог сайта и поправьте «URL страницы детального просмотра» в настройках инфоблока.
  
• Ссылки на модели в гараже или в карточке ведут на пустую страницу. Укажите в параметре CATALOG_URL реальный адрес страницы каталога с подбором или настройте страницы подбора с ЧПУ.
  
• В адресе страницы модели или в sitemap нет нужной модели. Заполните символьные коды («Заполнить пустые коды») и проверьте активность и видимость на сайте у модели и всех элементов над ней.
  
• Автоимпорт: «Адрес файла недоступен». Адрес ведёт во внутреннюю сеть, на сам сервер, на порт, отличный от 80 и 443, или переадресует туда. Выложите файл по публичному адресу или в папку /upload/xlogic.compatibility/. «Источник автоимпорта не сохранён» — адрес или путь не подходит под эти правила.
  
• Импорт: «товар … не найден». Проверьте настройку «Колонка PRODUCT файла содержит», инфоблок каталога и код свойства.
  
• Кнопки демо-данных неактивны. Нужно право записи в модуле «Информационные блоки» или права администратора.
  
• Изменения в дереве не видны на сайте. Кеш сбрасывается сам при управляемом кешировании; если оно выключено, сбросьте кеш сайта вручную.