Документация

Установите qwelp.loyalty через Marketplace / список решений. Нужны main, sale, catalog, iblock и currency, PHP от 8.2 в поддерживаемой платформой ветке и UTF-8. Для MySQL используется версия 8.0 или новее. Установщик добавляет пять компонентов и инфоблок условий программы; страницы, меню и чужие шаблоны он не переписывает.

Примеры предназначены для уже работающей страницы Битрикс, между header.php и footer.php, либо для копии шаблона компонента. Каждый IncludeComponent размещайте в отдельном блоке <?php … ?>. Несколько вызовов в одном блоке визуальный редактор может сохранить как один.

Если PHP уже открыт, не вставляйте второй открывающий тег внутрь него. SITE_ID='' означает текущий сайт. Оставляйте простые значения в массиве параметров; вычисления цены выполняются внутри компонента. После правки сохраните параметры в редакторе без изменений и с изменением одного значения, затем проверьте страницу.

Marketplace размещает модуль в /bitrix/modules/qwelp.loyalty/. Установщик добавляет пять компонентов в /bitrix/components/qwelp/ и расширения JS в /bitrix/js/qwelp/loyalty/. Административные страницы находятся в /bitrix/admin/qwelp_loyalty_*.php. Файлы ядра и чужих модулей не изменяются.

Установите модуль один раз на общую установку Битрикса. Для сайтов на разных доменах с общей символьной ссылкой /bitrix компоненты, скрипты и обновления доступны сразу на обоих сайтах. Ссылка /local для работы самого модуля не требуется. Общий /upload нужен стандартным данным Битрикса; /images зависит от устройства вашего сайта.

Добавьте нужные IncludeComponent на страницы каждого сайта. Оставьте SITE_ID пустым: карточка, корзина, баланс и списание определят текущий сайт. Балансы, история, заказы и купоны разделены по SITE_ID; общие настройки программы действуют на всю установку, а отдельное правило можно ограничить сайтом. Удаление модуля отключает его на всех сайтах общей установки.

В настройках «Композитный сайт» внесите оба домена. Установка модуля не включает Composite и не меняет настройки сайтов автоматически. Если для второго сайта нужны собственные тексты условий, создайте отдельный инфоблок и задайте IBLOCK_ID у loyalty.page; по умолчанию используется общий инфоблок условий.

Копии шаблонов в /local/templates/ остаются пользовательскими настройками. На раздельных корнях сайтов разместите свою копию на каждом нужном сайте либо используйте общий шаблон. Копии самих компонентов или JS в /local имеют приоритет над /bitrix и могут скрыть обновлённый модуль. Старую разработческую установку с файлами в /local сначала удалите с сохранением данных; затем установите пакет Marketplace. Не держите одновременно две копии qwelp.loyalty в /local/modules и /bitrix/modules.

В script.js той же копии найдите метод setPrice: function(). Вставьте этот фрагмент в самый конец тела метода, перед его закрывающей скобкой. Не вставляйте его за пределами метода: price и this относятся к текущей карточке.

var loyaltyApi = BX.Qwelp && BX.Qwelp.Loyalty && BX.Qwelp.Loyalty.Earning;
var loyaltyRoot = this.obProduct && this.obProduct.querySelector('[data-qwelp-loyalty-earning]');
if (loyaltyApi && loyaltyRoot) {
    loyaltyApi.updateProduct(
        loyaltyRoot,
        price ? Number(price.PRICE) : 0,
        this.obQuantity ? Number(this.obQuantity.value) : Number(this.stepQuantity || 1),
        this.canBuy === true || this.canBuy === 'Y'
    );
}

Если рядом есть script.min.js или script.map.js, пересоберите их из изменённого script.js либо удалите эти два сгенерированных файла только из вашей копии шаблона. Иначе Битрикс может продолжить отдавать старый минифицированный код. После этого сбросьте кеш компонента и объединённых JS-файлов штатной кнопкой «Сбросить кеш».

Штатный setPrice() вызывается после изменения количества, ценового диапазона и предложения. Используется PRICE за одну единицу × количество; RATIO_PRICE уже содержит коэффициент единицы измерения и здесь не нужен. Очистите кеш страницы и JS, смените SKU и количество, проверьте недоступное предложение. Для изменённого сторонним разработчиком script.js сначала сверьте наличие этих полей.

Если на странице установлен «Каталог», а отдельного catalog.element в списке компонентов страницы нет, копируйте активный шаблон комплексного каталога в /local/templates/.default/components/bitrix/catalog/loyalty_catalog/ и выберите эту копию в параметрах каталога.

Внутри копии найдите вложенный bitrix/catalog.element/ИМЯ_ВЛОЖЕННОГО_ШАБЛОНА/. Правьте его template.php и script.js. Если папки нет, посмотрите имя шаблона во вложенном вызове catalog.element в element.php: скопируйте соответствующий стандартный шаблон в эту вложенную папку. Пустое имя означает .default.

Не размещайте прогноз в element.php рядом с вызовом catalog.element: в этой точке нет результата самого товара. Вставка должна находиться в шаблоне карточки под ценой.

В шаблоне bitrix:catalog.item используется такой же вызов с $component. Поддержаны ITEM, OFFERS/OFFERS_SELECTED, ITEM_PRICES/ITEM_PRICE_SELECTED/RATIO_PRICE и MIN_PRICE/DISCOUNT_VALUE. При другой структуре данных используйте параметры из вкладки «Параметры» и передавайте цену через updateProduct.

В свой обработчик цены передавайте DOM-корень именно изменённой карточки, цену числом за одну единицу, количество и boolean доступности. Этот прогноз показывает безусловный базовый бонус; персональные акции окончательно рассчитываются по заказу.

Скопируйте активный шаблон корзины в /local/templates/.default/components/bitrix/sale.basket.basket/loyalty_basket/ и выберите loyalty_basket в параметрах. Разместите вызовы в его template.php в отдельном контейнере, который AJAX не пересоздаёт. Не вставляйте PHP в клиентский шаблон строки товара: он заполняется JavaScript.

Сначала проверьте простой вариант под корзиной. Он позволяет убедиться, что модуль работает, до изменения расположения.

Если свой шаблон не отправляет OnBasketChange, после сохранения корзины и пересчёта её цен отправьте:

BX.onCustomEvent('QwelpLoyalty:onBasketRefresh');

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

CHECKOUT вызывает штатный BX.Sale.OrderAjaxComponent.sendRequest('refreshOrderAjax'). Не добавляйте второй обработчик того же пересчёта.

Прогноз берётся по сохранённым товарам корзины. Ещё не сохранённые условия доставки, оплаты и свойства заказа могут повлиять на окончательное начисление после оплаты. Максимум списания сервер проверяет повторно; доставка его не увеличивает.

REFRESH_MODE=CHECKOUT подходит только при наличии штатного BX.Sale.OrderAjaxComponent. Для другого оформления выберите EVENT. В своём скрипте один раз подпишитесь на QwelpLoyalty:onChanged, выполните штатный пересчёт вашего заказа и после его завершения отправьте QwelpLoyalty:onBasketRefresh.

Событие onChanged передаёт siteId и action (redeem или cancelCurrentRedeem). Без обработчика пересчёта режим EVENT не завершает подключение. Не заменяйте собственную форму заказа копией шаблона shop.light.

Пустой ORDER_URL_TEMPLATE использует personal/orders/#ID#/ от корня текущего сайта. Если у вас другие адреса, задайте свой локальный путь с #ID#.

IBLOCK_ID=0 выбирает инфоблок модуля, LANGUAGE_ID='' — текущий язык. У элементов контента BLOCK_TYPE задаёт блок, LANGUAGE — язык, EXTRA_VALUE — подпись, номер или локальный URL. Подстановки #EARN_PERCENT#, #POINT_RATE#, #PENDING_DAYS#, #EXPIRE_DAYS# и #MIN_REDEEM_POINTS# берут значения из настроек.

Отдельный универсальный компонент отчёта о баллах одного заказа не поставляется. Для такого отчёта разработчик может использовать OrderBonusViewService после проверки доступа к заказу.

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

<?php
$APPLICATION->IncludeComponent('qwelp:loyalty.earning', '', [
    'MODE' => 'PRODUCT', 'USE_PARENT' => 'N',
    'UNIT_PRICE' => '1000', 'QUANTITY' => '1', 'AVAILABLE' => 'Y', 'SITE_ID' => '',
]);
?>

В настоящей карточке передавайте цену из её модели через updateProduct; не оставляйте тестовую цену 1000.

Права D/R/W задаются через «Настройки → Настройки продукта → Настройки модулей → qwelp.loyalty → Доступ». Для чтения документации достаточно R.

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

<?php if (\Bitrix\Main\Loader::includeModule('qwelp.loyalty')): ?>
<?php
$APPLICATION->IncludeComponent('qwelp:loyalty.summary', '', ['SITE_ID' => '']);
?>
<?php endif; ?>

Стандартные account, summary и redeem сначала выводят нейтральный HTML, затем получают значения текущего пользователя через AJAX. Не записывайте баланс или историю в общий кеш родительского компонента. Ответ getBalance запрещает кеширование и не принимает ID другого покупателя; historyLimit ограничен диапазоном 0–100, для краткого баланса используйте 0. При выходе из аккаунта или восстановлении страницы из истории браузера данные запрашиваются заново.

Если раньше копировали шаблоны этих компонентов, перенесите из текущей поставки нейтральную разметку и подключение JS-расширений. Один вызов setFrameMode(true) не защищает персональный HTML внутри общего кеша.

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

Проверьте сочетание с обычным промокодом, удаление/отложение товара и пустую корзину. Выключите программу на стенде: новые прогнозы и списание скрываются, существующее списание можно отменить.

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

На страницах с Композитом сделайте два анонимных запроса с одной сессией: второй должен вернуть X-Bitrix-Composite: Cache (200). Проверьте виджеты после загрузки динамических зон. Корзина и оформление могут работать без Композита.

Это проверка интеграции с вашим шаблоном. Подготовка самой поставки к Marketplace требует отдельной проверки установки, удаления и совместимости.

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