Модуль 1С-Битрикс (new)

Описание модуля

Программный модуль для упрощения интеграции сервиса программ лояльности  MAXMA.com  в веб-сайты брендов-партнеров, работающих на платформе 1С-Битрикс.
В модуле реализованы:
  • Обработчики событий стандартных модулей 1С-Битрикс
  • Правила работы с корзиной
  • Функции отключения обработки заказов для группы пользователей
  • Отложенная отправка ошибочных запросов к API
  • Компоненты публичной части
  • Логирование данных
Доп. описание
  • Регистрация в программе лояльности
  • Просчет скидок в КОРЗИНЕ- Списание бонусов- применение промокодов- применение подарочных карт- применение акций maxma
  • Просмотр максимального списания бонусов в корзине
  • Просмотр начисленных бонусов в карточке товара
  • Просмотр скидок на товар и бонусов, которые будут начислены за покупку, в карточке товара
  • Просмотр баланса бонусного счета и истории начислений и списаний

Технические требования

  • 1С-Битрикс ≥ 18.5
  • PHP ≥ 7.0

Установка и настройка

Установка

Модуль можно установить на проект с официального  маркетплейса 1С-Битрикс .
При установке модуль:
  • Регистрирует обработчики для событий OnAfterUserAdd, OnAfterUserAuthorize , OnBeforeSaleOrderFinalAction , OnSaleOrderCanceled , OnSaleStatusOrderChange, OnSaleOrderBeforeSaved , OnSaleOrderSaved, OnProlog
  • Создает таблицу maxma_delayed_request для хранения данных об отложенных запросах
  • Создает таблицу maxma_product_discount для хранения данных для расчета скидки позиции корзины заказа
  • Создает правило работы с корзиной Скидка MAXMA
  • Создает свойства заказа:
  • MAXMA_BONUSES для хранения бонусов, применённых к корзине заказа
  • MAXMA_PROMOCODE для хранения примененного промокода
  • Регистрирует агенты:
  • \\Maxma\\Loyalty\\RequestQueue\\QueueCleaner::agentQueueCleaner(); для очистки обработанных записей в таблице maxma_delayed_request
  • \\Maxma\\Loyalty\\RequestQueue\\QueueExecutor::agentQueueExecute(); - для обработки записей в таблице maxma_delayed_request

Настройка

Модуль содержит настройки в административной части сайта Настройки продукта > Настройки модулей > MAXMA Loyalty
Список настроек:
  • Секретный ключ — секретный API ключ для интеграции, можно получить у вашего менеджера.
  • Код точки продаж — идентификатор вашего магазина (цифры, символы).
  • Адрес сервера для отправки запросов
  • Боевой режим —  api.maxma.com 
  • Тестовый режим —  api-test.maxma.com 
  • Статус выкупа заказа — набор статусов, при которых заказ будет помечен выкупленным в MAXMA.
  • Включить логирование — логи хранятся в папке модуля в logs/, сгруппированные по дням.
  • Ограничения процессинга — используйте эту настройку, чтобы исключить служебных пользователей из процессинга заказов. Например, при синхронизации с 1С.
  • Отправлять только активных пользователей - используйте эту настройку, если у вас включена регистрация по номеру телефона, и вы не хотите, чтобы в MAXMA уходили еще не подтвержденные номера.
  • Применять в запросах телефон - при получении данных о клиентах вместо идентификатора Битрикс для сопоставления будет использован мобильный телефон.
  • Передавать в операциях внешний ID - при получении данных о товарах вместо ID товара будет использоваться его внешний код для сопоставления.
  • Отправлять только пользователей с телефоном - используйте эту настройку, чтобы в MAXMA не отправлялись пользователи, у которых не заполнен номер телефона.

Логирование

Логирование реализовано в классе Util/Logger. Логи записываются в директорию /logs/ в корне проекта. Лог-файлы имеют расширение .log
Доступно 8 уровней логирования ( PSR-3 ).
Пример вызова логирования:
// данный вызов создаст файл client.log в директории /logs/{текущий день}/
// и запишет в файл лог уровня info
// @var string $message Сообщение лога
// @var array $context Дополнительные данные логирования
\Maxma\Bitrix\Util\Logger::channel('client')->info($message, $context);
Запись логов зависит от активной настройки модуля logging.
В случае если нужно записать в логи, а настройка выключена, есть специальный метод enableLogging() . Предназначение данного метода — это отладка на клиентских проектах отдельных узлов модуля.

Отложенные запросы

Функционал отложенной отправки запросов нужен для безотказной передачи данных с сайта в API MAXMA. При отправке запросов через SDK MAXMA и получении исключения TransportException сохраняем данные и операцию в базу данных в таблицу maxma_delayed_request. Класс описывающий таблицу — Maxma\Loyalty\RequestQueue\QueueTable
Методы API, для которых настроена отложенная отправка:
  • Создание нового клиента
  • Обновление externalId клиента
  • Создание и изменение заказа
  • Выкуп заказа
  • Отмена заказа

Бизнес-логика

Покупатели

Для создания новых покупателей в MAXMA используются обработчик двух событий:
  • OnAfterUserAdd (добавление пользователя на сайте)
  • OnAfterUserAuthorize (авторизация пользователя на сайте)
Обработчик выполняет поиск покупателя в базе MAXMA и в соответствии с результатом регистрирует его, изменяет данные или не выполняет никаких действий.
Обработчик и поиск покупателя в MAXMA работает по следующей бизнес-логике:
    Если отмечена настройка “Отправлять только пользователей с телефоном”, но при этом у пользователя телефон не заполнен, дальнейшие действия не происходят.
    Если отмечена настройка “Применять в запросах телефон”, первичная проверка пользователя производится по номеру телефона, если он заполнен. В противном случае, проверка происходит по внешнему идентификатору (узел externalId). Если покупатель найден, никаких действий не выполняется.
    Если покупатель не найден по externalId , производится поиск по номеру телефона. Значение берется из поля Bitrix PHONE_NUMBER, а если оно пусто, то из поля PERSONAL_PHONE. Для ситуаций, когда на сайте номер телефона хранится не в стандартных полях сущности пользователя, надо создать обработчик на событие модуля onGetUserPhone.
    Если покупатель найден по телефону, выполняется обновление внешнего идентификатора (externalId) в MAXMA. В качестве значения узла externalId надо передается составное значение из префикса bx- и идентификатора пользователя в Bitrix (например, bx-337).
    Если покупатель не найден по externalId и phoneNumber, он создается в MAXMA.

Заказы

Для создания и обновления заказов используется обработчик, который привязан к событию OnSaleOrderSaved (происходит в конце сохранения заказа).
При создании нового заказа переносятся значения списанных бонусов и промокода из сессии в свойство заказа MAXMA_BONUSES и MAXMA_PROMOCODE.
Для фиксации выкупа заказа используется обработчик события OnSaleStatusOrder (происходит после изменения статуса заказа).
Для фиксации отмены заказа используется обработчик события OnSaleOrderCanceled (изменение флага отмены заказа).
Модуль не поддерживает частичный возврат заказа.

Расчет скидок

Применение скидки MAXMA реализовано через пользовательское правило работы с корзиной.
Хранилище для правил работы с корзиной реализовано в виде таблицы в базе данных. Название таблицы — maxma_product_discount. Взаимодействие с таблицей реализовано через ORM D7.
Для обработки данной операции реализована привязка к событию OnBeforeSaleOrderFinalAction (финальный расчет корзины).
Расчет скидки производится при следующих события:
  • Списание бонусов через компонент maxma:basket.bonus
  • Применение промокода через компонент maxma:basket.promocode
  • Пересчет заказа

Расчет бонусов в каталоге

Для расчета бонусов и скидок в каталоге на месте вывода цены необходимо разместить компонент maxma:catalog.element.price.
Ранее полученные бонусы и скидки хранятся в sessionStorage (очищается при завершении сессии либо по истечении 1 часа).
При загрузке страницы вызывается событие maxmaPricesGet, к которому привязано получение скидок и бонусов из Maxma. Это же событие необходимо вызывать при ajax-подгрузке товаров.
На событии maxmaPricesGet происходит проверка, не устарели ли по времени текущие данные, хранящиеся в sessionStorage, и имеются ли они вообще. При необходимости обновить данные js-скрипт обходит блоки с ценами, размеченные внутри компонента и сверяет их с теми, что сохранены в sessionStorage. Те товары, которые не были ранее сохранены, или у которых изменилась цена, запрашиваются у MAXMA по API. Новые полученные данные добавляются в sessionStorage, после чего данные в размеченных блоках с ценами подменяются на новые - с ценой до скидки, ценой после скидки и бонусами за начисление (если таковые имеются).

Компоненты

Компонент баллов в карточке товара

Компонент отображает количество бонусов, которое будет начислено при покупке товара.
Место интеграции — карточка товара.
Компонент получает данные о количестве бонусов из API MAXMA.
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:catalog.element.bonus',
'',
[
'PRICE' => $item['BASE_PRICE'],
'PRODUCT_ID' => $item['ID']
],
$component,
['HIDE_ICONS' => 'Y']
);
?>

Компонент скидки и бонусов в карточке товара

Компонент отображает цену со скидкой MAXMA и бонусы к начислению за покупку товара.
Компонент размещается на месте вывода цены в карточке товара либо в компоненте bitrix:catalog.section или bitrix:catalog.item, после чего кастомизируется под дизайн сайта.
Цена и бонусы подтягиваются из sessionStorage в следующий блок:
<span
data-entity="maxma-price"
data-id="<?= $arParams['PRODUCT_ID'] ?>"
data-sku="<?= $arParams['SKU'] ?>"
data-price="<?= $arParams['PRICE'] ?>"
data-currency="<?= $arParams['CURRENCY']?>"
>
Data-атрибуты необходимо сохранить для корректной работы компонента.
Параметры:
PRODUCT_ID - идентификатор товара
SKU - артикул товара
PRICE - цена товара в числовом формате
Пример вызова
<?$APPLICATION->IncludeComponent(
"maxma:catalog.element.price",
"",
[
"PRODUCT_ID" => $item['ID'],
"SKU" => \Maxma\Loyalty\Entity\Product::getProductSKU($item[‘ID’]),
"PRICE" => $item['PRICE'],
]
);?>
Пример внешнего вида в каталоге и в карточке товара

Компонент бонусов в корзине

Компонент отображает количество бонусов покупателя и содержит форму списания бонусов при оформлении заказа.
Место интеграции — корзина и страница оформления заказа.
Компонент доступен только для авторизованного пользователя.
При инициализации компонента на странице происходит получение информации о списанном текущем количестве бонусов из глобальной переменной сессии под ключом MAXMA_BONUSES и отображается в форме, если оно не пустое.
При отправке формы списания бонусов выполняется запрос в MAXMA с данными пользователя, количеством бонусов к списанию, корзиной заказа, данными промокода (ключ MAXMA_PROMOCODE переменной сессии).
Полученный расчет корзины с учетом списанных бонусов фиксируется в таблице maxma_product_discount. Количество бонусов, которые были списаны пользователем, фиксируются в сессии под ключом MAXMA_BONUSES.
При отмене списания бонусов значение в сессии под ключом MAXMA_BONUSES очищается.
Компонент содержит 2 шаблона: полный (default) и сокращенный (short).
Параметры компонента:
Название
Параметр
Описание
Страница авторизации
PATH_TO_AUTH
Путь до страницы авторизации
Подробная информация
DETAILED_LINK
Ссылка на страницу с подробной информацией
Ajax запрос
IS_AJAX
Работа в режиме Ajax (доступен только для стандартных компонентов Bitrix)
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:basket.bonus',
'short',
[
'PATH_TO_AUTH' => '/login/',
'DETAILED_LINK' => ' https://maxma.com/ru ',
'IS_AJAX' => 'Y'
],
false
);
?>

Компонент промокода в корзине

Компонент представляет собой форму ввода и применения промокода.
Место интеграции — корзина, страница оформления заказа.
Компонент доступен для авторизованного и неавторизованного пользователя.
При инициализации компонента на странице происходит получение информации о примененном промокоде из глобальной переменной сессии под ключом MAXMA_PROMOCODE и отображается в форме, если оно не пустое.
При отправке формы промокода выполняется запрос в MAXMA с данными пользователя, промокодом, корзиной заказа, количеством списанных бонусов (ключ MAXMA_BONUSES переменной сессии).
При успешном применении промокода его значение записывается в переменной сессии под ключом MAXMA_PROMOCODE и полученный расчет фиксируется в таблице maxma_product_discount.
При отмене применения промокода значение в сессии под ключом MAXMA_PROMOCODE очищается.
Компонент содержит 2 шаблона: полный (default) и сокращенный (short).
Параметры компонента:
Пример вызова:
<?$APPLICATION->IncludeComponent(
'maxma:basket.promocode',
'short',
[
'IS_AJAX' => 'Y'
],
false
);?>

Компонент баланса бонусного счета

Компонент предполагается размещать внутри личного кабинета. Доступен только для авторизованных пользователей.
В компоненте отображается текущее количество баллов на счету клиента, а также бонусные баллы, которые ожидаются к зачислению, и баллы, которые сгорят в ближайшее время.
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:personal.bonus',
''
);
?>
Пример внешнего вида в личном кабинете:

Компонент истории бонусного счета

Компонент предполагается размещать внутри личного кабинета. Доступен только для авторизованных пользователей.
В компоненте отображаются записи об изменениях состояния балансного счета пользователя: начисления, списания, сгоревшие баллы.
Параметры компонента:
PAGE_ELEMENT_COUNT - Количество записей на странице.
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:personal.bonus.history',
'',
[
'PAGE_ELEMENT_COUNT' => 10
]
);
?>
Пример внешнего вида в личном кабинете:

Кастомизация компонентов

Для подготовки дизайна интерфейса компонентов рекомендуется использовать макеты в  Figma :
Для кастомизации цветов компонента необходимо в глобальном файле стилей сайта добавить правило с объявлением CSS переменных:
:root .maxma {
--maxma-accent-color: #1CA1BD; /* базовый цвет */
--maxma-success-color: #87C73D; /* цвет успешной операции */
--maxma-error-color: #C71E1E; /* цвет ошибки */
--maxma-main-hover-color: #5B9F0B; /* цвет при наведении */
}
Если нужны более сложные изменения в визуальной части компонента, необходимо скопировать дефолтный шаблон компонента в соответствующую директорию шаблона сайта и внести изменения.

Порядок поддержки модуля

Поддержка (вопросы, ошибки, идеи) осуществляется по электронной почте  support@maxma.com .
Режим работы: 09:00-18:00 по московскому времени. Выходные дни: суббота и воскресенье.
Время реакции на обращение – 24 часа.

Структура модуля

Файловая структура

  • lang/ru/ — каталог с языковыми файлами скриптов модуля;
  • lib/ — каталог с классами, реализующие основную бизнес-логику;
  • logs/ — каталог с логами;
  • install/ — каталог с файлами используемыми для инсталляции и деинсталляции модуля;
  • components/maxma/basket.bonus/ — каталог компонента списания бонусов;
  • components/maxma/basket.promocode/ — каталог компонента промокода;
  • components/maxma/catalog.element.bonus/ — каталог компонента отображения бонусов в карточке товара;
  • components/maxma/catalog.element.price/ - каталог компонента отображения цены со скидкой и бонусов к начислению в карточке товара;
  • components/maxma/personal.bonus/ - каталог компонента отображения баланса бонусного счета в личном кабинете
  • components/maxma/personal.bonus.history - каталог компонента отображения истории начислений и списаний с бонусного счета в личном кабинете;
  • index.php — файл с описанием модуля;
  • version.php — файл с номером версии модуля.
  • vendor/ — каталог с зависимостями модуля;
  • .settings.php - в файле описаны контроллеры для действий
  • composer.json — конфиг для composer;
  • include.php — файл для подключения автолоадера composer;
  • default_option.php — содержит массив с именем $ID модуля_default_option, в котором заданы значения по умолчанию для параметров модуля;
  • options.php — страница настроек модуля;
  •  README.md  — описание модуля

Структура классов

  • Maxma — класс ответственен за получение и настройку экземпляра SDK MAXMA. В классе описаны основные необходимые операция для взаимодействия с API.
  • Settings — класс реализует шаблон Singleton и нужен доступа к настройкам модуля. Хранит код модуля и реализовано получение настроек модуля через COption.
  • Exceptions/ — неймспейс для хранения исключений модуля.
  • Entity/Order — класс, содержащий основную бизнес-логику сущности заказа.
  • Entity/User — класс, содержащий основную бизнес-логику сущности пользователя.
  • Entity/Product— класс, содержащий основную бизнес-логику сущности товар.
  • Event/CommonEvent - события на загрузке страницы. Здесь происходит подгрузка скриптов для подмены цен.
  • Event/UserEvent — события для работы с пользователем.
  • Event/OrderEvent — события для работы с заказом.
  • Util/Logger — класс для логирования в проекте.
  • Util/Helper — класс со статическими методами для типовых действий.
  • RequestQueue/QueueExecutor — класс реализует функционал добавления запроса в очередь (записать в хранилище), исполнение запроса.
  • RequestQueue/QueueCleaner — класс реализует функционал очищения отработанных очередей. Функционал запускается агентом.
  • RequestQueue/QueueTable — класс описывает таблицу при помощи ORM Bitrix.
  • Install/Discount— класс реализует установку пользовательское правила работы с корзиной.
  • Install/OrderProperty — класс реализует установку свойств заказа Bitrix.
  • Discount/CartRuleAction — класс, описывающий кастомное правило работы с корзиной.
  • Discount/DiscountStorageTable — orm аннотация таблицы maxma_product_discount.
  • Discount/DiscountManager — реализация расчета скидки.
  • Enum/EntityNameEnum — класс-перечисление, хранящий названия дополнительных сущностей модуля.
  • Enum/SettingsEnum — класс-перечисление, хранящий символьные коды настроек модуля.
  • Controller - неймспейс для контроллеров модуля
  • Controller\Product - класс для действий с товарами.

Зависимости проекта

  •  https://github.com/cloudloyalty/client-php 
  •  https://github.com/php-fig/log 
  •  https://github.com/myclabs/php-enum