- Возможности интеграции с программой лояльности
- Установка и настройка программы лояльности
- Дополнительные настройки
- Техническая документация
- Используемые компоненты
- Процесс установки
- Кастомизация шаблонов
- Общая информация
- API программы лояльности
- Контроллеры
- Принцип работы
- Адрес контроллера
- Спецификация контроллеров
- Сервисы
- Спецификация сервисов
- Обработчики событий
Программа лояльности (ПЛ) доступна в системе начиная с версии 8.0.0. Функции программы лояльности доступны в модуле интеграции с версии 6.0.0.
Возможности интеграции с программой лояльности
Модуль с функциями программы лояльности позволит:
- зарегистрироваться клиентам в программе лояльности;
- выводить актуальную информацию об участии в программе лояльности в личном кабинете клиента (количество бонусов, текущий уровень и пр.);
- оплачивать часть заказа бонусами;
- отображать количество бонусов, которое будет начислено по каждому товару отдельно и за весь заказ;
- использовать скидки, предоставляемые согласно уровню привилегии клиента;
- синхронизировать данные по программе лояльности между системой и 1С-Битрикс.
Также модуль поддерживает функции SMS-верификации при регистрации клиента в программе лояльности (подтверждение номера телефона) и при списании бонусов для оплаты заказа.
Установка и настройка программы лояльности
Перед началом настройки на стороне 1C-Битрикс необходимо убедиться, что в системе программа лояльности настроена и активирована. Подробнее о настройке программы лояльности читайте в соответствующем разделе.
Программа лояльности доступна в модуле интеграции RetailCRM для 1С-Битрикс начиная с версии ядра 20.0.0.
Для работы программы лояльности необходим установленный модуль «Интернет магазина» (Sale), который доступен в лицензиях «Малый бизнес», «Бизнес», «Энтерпрайз». А также модуль Highloadblock.
Важно!
Программа лояльности в 1С-Битрикс работает только при активной настройке «Выгрузка заказов по событию» в модуле интеграции.
Шаг 1 - Установка модуля
Для активации программы лояльности нужно обновить модуль RetailCRM до последней версии (6.0.0), либо, если модуль еще не установлен, установить его из маркетплейса 1С-Битрикс.
Шаг 2 - Активация программы лояльности
После установки или обновления модуля в настройках станет доступна вкладка «Программа лояльности».
В данном разделе нужно включить опцию «Активность программы лояльности» и нажать «Сохранить».
Шаг 3 - Настройка компонентов
Модуль предоставляет возможность внедрить поддержку программы лояльности в 4 компонентах:
- Настраиваемая регистрация (
bitrix:main.register) - Корзина (
bitrix:sale.basket.basket) - Оформление заказа (
bitrix:sale.order.ajax) - «Персональный раздел пользователя» (
bitrix:sale.personal.section)
Для первых трех компонентов допускается просто заменить текущий шаблон на шаблон default_loyalty в параметрах компонента.
Примечание
Если в параметрах компонента этого шаблона нет, то активировать его можно в настройках модуля.
Для настройки «Персонального раздела пользователя», заполните параметры компонента следующим образом:
- в поле «Путь к дополнительной странице» укажите
/lp-score. На данной странице будет представлена информация по участию клиента в программе лояльности (текущий уровень, доступные привилегии и т.п.). - в поле «Название страницы» укажите название раздела, в котором будет представлена информация по программе лояльности.
- «Имя класса FontAwesome» укажите название иконки, которая будет отображаться для раздела программы лояльности, например, «
fa-diamond».
Значения в полях «Название страницы» и «Имя класса FontAwesome» могут быть любыми, на функциональность модуля они не влияют.
После применения данных настроек в личном кабинете должен появиться новый раздел с названием, указанным в поле «Название страницы».
Важно!
Функции программы лояльности корректно работают только с физическими лицами.
Дополнительные настройки
Дополнительные настройки разбиты на 3 блока:
- Управление компонентом Оформление заказа (
sale.order.ajax); - Управление компонентом регистрации (
main.register); - Управление компонентом корзины (
sale.basket.basket);
Кнопка «Создать шаблон»
Данная кнопка стирает шаблон компонента default_loyalty из директории /local/templates/.default/components/bitrix/название_шаблона и заменяет его новым, скопированным из директории модуля.
Важно!
Эта операция не обратима и может привести к затиранию данных в том случае, если были внесены правки в шаблон
default_loyalty.
Кнопка «Заменить шаблон»
Позволяет заменить шаблон компонента .default для выбранных шаблонов сайта, на шаблон с функциями программы лояльности (данные для замены аналогичны шаблону default_loyalty). При этом, если у вас уже существует шаблон .default, то его содержимое будет перемещено в .default_backup.
Список доступных шаблонов для замены расположен справа от кнопки «Заменить шаблон».
Механизм замены шаблонов можно использовать, когда на какой-то странице уже размещен нужный компонент с шаблоном .default и вы хотите быстро заменить этот шаблон на шаблон .default с функциями программы лояльности.
Важно!
Если заменяемый шаблон
.defaultбыл модифицирован, то изменения, сделанные в нем, не будут перенесены в шаблон, который будет его заменять.
Пользовательские соглашения
В настройках компонента регистрации (main.register) имеются две ссылки на редактирование пользовательских соглашений:
- Соглашение на обработку персональных данных;
- Согласие с условиями программы лояльности.
Данные соглашения принимает клиент при регистрации в программе лояльности. Необходимо заполнить соглашения согласно условиям участия в программе лояльности.
Техническая документация
Используемые компоненты
Программа лояльности может работать со следующими компонентами:
- Настраиваемая регистрация (
bitrix:main.register) с шаблономdefault_loyaltyили модифицированным.default. - Настраиваемая регистрация (
intaro:main.register) с шаблоном.default. - Корзина (
bitrix:sale.basket.basket) с шаблономdefault_loyaltyили модифицированным.default. - Корзина (
intaro:sale.basket.basket) с шаблоном.default. - Оформление заказа (
bitrix:sale.order.ajax) с шаблономdefault_loyaltyили модифицированным.default. - Оформление заказа (
intaro:sale.order.ajax) с шаблоном.default. - «Личный кабинет в программе лояльности» (
intaro:lp.score). - Регистрация в программе лояльности (
intaro:lp.register) с шаблоном.default.
Чтобы использовать компоненты с функциями программы лояльности нужно разместить их на отдельных страницах.
Процесс установки
1.У сущности «пользователь» появляются новые поля:
- Строковое значение «Номер карты программы лояльности»;
- Строковое значение «Номер аккаунта в программе лояльности»;
- Булево значение «Зарегистрироваться в программе лояльности»;
- Булево значение «Я согласен с условиями программы лояльности»;
- Булево значение «Согласие на обработку персональных данных»;
- Булево значение «Активность в программе лояльности».
Эти поля можно найти в профиле любого пользователя на вкладке «Доп. поля».
2.Создаются обработчики событий, которые расположены в классе Intaro\RetailCrm\Component\Handlers\EventsHandlers:
OnSaleComponentOrderResultPreparedHandler- обработчик события, вызываемого при обновлении еще не сохраненного заказа.OnSaleOrderSavedHandler- обработчик события, вызываемого ПОСЛЕ сохранения заказа (OnSaleOrderSaved).OnAfterUserRegisterHandler- обработчик события, регистрирующий пользователя в CRM системе после регистрации на сайте.addUpdateLoyaltyButton- обработчик события, срабатывающий перед открытием заказа в административной панели, для обновления информации о Программе лояльности в административной панели.
3.Создается директория local в корне сайта (если она еще не была создана) со следующей структурой:
В данную директорию копируются компоненты пространства intaro:
lp.register- компонент регистрации в программе лояльности;lp.score- компонент, отображающий информацию об участии в программе лояльности в личном кабинете клиента;main.register- компонент регистрации на сайте с возможностью регистрации в программе лояльности (создан на основеbitrix:main.register);sale.basket.basket- компонент корзины (модифицированныйbitrix:sale.basket.basket), отображает количество баллов, которые будут начислены за весь заказ и за каждый товар в отдельности, или скидки, применяемые согласно уровню привилегии клиента.sale.order.ajax- компонент оформления заказа (модифицированныйbitrix:sale.order.ajax).
4.Создаются две директории в корне сайта (в каждой только один файл - index.php):
lp-register- в индексном файле размещен компонентbitrix:main.registerс модифицированным дефолтным шаблономdefault_loyalty. Доступ к странице можно получить по адресуyoursite/lp-register.lp-score- в индексном файле размещен компонентintaro:lp.score. Доступ к странице можно получить по адресуyoursite/lp-score.
5.Создаются два соглашения, которые можно найти по адресу yoursite/bitrix/admin/agreement_edit.php), они могут использоваться при регистрации в Программе лояльности:
6.Создается директория с js библиотеками, расположенная по адресу /bitrix/js/intaro. В ней хранятся некоторые js библиотеки, используемые в модуле. К ним можно обращаться через CUtil::InitJSCore([псевдоним библиотеки]]. Зарегистрированные библиотеки можно посмотреть в файле intaro.retailcrm/include.php.
7.Создается Highload-блок «Программа лояльности» для записи информации, необходимой для корректного обмена данными.
Кастомизация шаблонов
Общая информация
Правила кастомизации шаблонов компонентов Программы лояльности соответствуют общим правилам кастомизации шаблонов 1С-Битрикс, описанных в курсе Кастомизация шаблонов компонентов.
Перед кастомизацией рекомендуем скопировать шаблон кастомизируемого компонента:
- если это компонент
intaro, то в директорию/local/components/intaro/название_компонента/templates/ваше_название_шаблона - если это стандартный компонент Bitrix, то нужно скопировать шаблон из директории
/local/templates/.default/components/bitrix/название_компонента/default_loyaltyв директорию/local/templates/.default/components/bitrix/название_компонента/ваше_название_компонента
Важно!
Копирование шаблона защищает от случайного затирания, которое может произойти, например, при повторном копировании шаблона через функции настроек модуля.
Перед загрузкой компонентов корзины и оформления заказа расчет бонусов и скидок программы лояльности происходит в result_modifier.php. В этих файлах блок, отвечающий за программу лояльности, выделен комментариями /** RetailCRM loyalty program Start*/ и /** RetailCRM loyalty program End*/.
Для асинхронного взаимодействия используются контроллеры, расположенные в пространстве имен Intaro\RetailCrm\Controller.
Кастомизация шаблонов компонентов регистрации bitrix:main.register, intaro:main.register, intaro:lp.register
Дополнительные данные в $arResult:
$arResult['LOYALTY_STATUS'] - содержит «Y», если программа лояльности включена в настройках модуля и «N», если нет.
$arResult['AGREEMENT_PERSONAL_DATA'] - содержит текст соглашения об использовании персональных данных.
$arResult[AGREEMENT_LOYALTY_PROGRAM] - содержит текст согласия с правилами программы лояльности.
$arResult['LP_REGISTER'] - содержит массив данных, необходимый для построения формы регистрации в программе лояльности. Его структура зависит от настроек программы лояльности (требуется ли смс-верификация, требуется ли заполнение дополнительных полей и т.д.). Пример структуры:
['msg' => сообщение для пользователя,
'form' => данные для построения формы[
'button' => [ кнопка формы
'name' => название кнопки,
'action' => название функции, которую необходимо вызвать по событию onclick,
],
'fields' => [ массив полей для заполнения, где ключ - это id поля, а значение - массив атрибутов.
'checkId' => [
'type' => 'hidden',
'value' => $smsCookie->checkId,
],
],
],
'resendAvailable' => дата в формате 'Y-m-d H:i:s', с временем, когда будет доступна повторная отправка смс,
'idInLoyalty' => id в программе лояльности]
Кроме того, в шаблонах используются следующие JS функции:
resendRegisterSms - повторно активирует пользователя. Если SMS-авторизация будет включена в настройках программы лояльности, то SMS будет отправлено повторно. Принимает на вход id в программе лояльности, делает ajax запрос к методу resendRegisterSmsAction класса Intaro\RetailCrm\Controller\Loyalty\Register. Полученные данные записывает в теги с id lpRegMsg (сообщение для пользователя) и checkIdField (код подтверждения, который необходим для SMS верификации).
sendVerificationCode - отправляет код верификации, полученный пользователем из SMS.
createAccount - сохраняет данные из полей программы лояльности в форме регистрации в профиль пользователя на Битриксе. Собирает информацию из полей формы регистрации и отправляет их в метод saveUserLpFieldsAction класса Intaro\RetailCrm\Controller\Loyalty\Register.
Изначально запрос на регистрацию пользователя в программе лояльности вызывается в методе OnAfterUserRegisterHandler класса Intaro\RetailCrm\Component\Handlers\EventsHandlers. Этот метод является обработчиком события OnAfterUserRegister и вызывается после регистрации пользователя в Битрикс.
Кастомизация компонента персональной информации об участии в программе лояльности intaro:lp.score
В отличии от других компонентов программы лояльности этот компонент не имеет аналога в пространстве bitrix, то есть компонента bitrix:lp.score не существует. Поэтому, в частности, вся логика вынесена не в result_modifier, как в остальных компонентах, а содержится в component.php.
Принцип работы компонента следующий: если пользователь не зарегистрирован в программе лояльности, то выводим форму, предлагающую зарегистрироваться (загружается компонент intaro:lp.register), а если зарегистрирован, то выводим состояние бонусного счета.
Данные в $arResult:
$arResult['LOYALTY_STATUS'] - активная ли программа лояльности (булевое значение).
$arResult['PERSONAL_LOYALTY_STATUS'] - существует ли аккаунт в программе лояльности у данного пользователя.
$arResult['BONUS_COUNT'] - количество бонусов на счете.
$arResult['ACTIVE'] - сообщение об активности в программе лояльности: «Да»/«Нет».
$arResult['CARD'] - номер бонусной карты.
$arResult['PHONE'] - телефон, указанный в программе лояльности.
$arResult['REGISTER_DATE'] - дата регистрации в программе лояльности.
Кастомизация шаблонов компонентов корзины bitrix:sale.basket.basket и intaro:sale.basket.basket
Шаблон .default intaro:sale.basket.basket создан на основе bitrix:sale.basket.basket .default. Отличия заключаются в функциональности программы лояльности, позволяющей видеть количество начисляемых бонусов как в целом по корзине, так и с детализацией по каждой позиции.
Дополнительные данные в $arResult:
$arResult['LOYALTY_STATUS'] - Активная ли программа лояльности (булевое значение)
$arResult['PERSONAL_LOYALTY_STATUS'] - Существует ли аккаунт в программе лояльности у данного пользователя
$arResult['TOTAL_RENDER_DATA']['WILL_BE_CREDITED'] - Сколько всего бонусов будет начислено за все товары в корзине
$arResult['BASKET_ITEM_RENDER_DATA'][номер_товара_в_корзине]['WILL_BE_CREDITED_BONUS'] - Сколько бонусов будет начислено за конкретный товар
В момент, когда происходит обновление корзины (например, изменяется количество товаров в заказе), вызывается свойство sendRequest объекта BX.Sale.BasketComponent, который расположен в файле путь_к_компоненту/sale.basket.basket/templates/.default/js/component.js.
Свойство sendRequest содержит в себе функцию, внутри которой и создается ajax запрос к контроллеру calculateBasketBonusesAction, пересчитывающему количество начисляемых бонусов.
Кастомизация шаблонов компонентов оформления заказа bitrix:sale.order.ajax и intaro:sale.order.ajax
Как и в случае с корзиной, шаблон .default intaro:sale.order.ajax создан на основе .default bitrix:sale.order.ajax, а шаблон intaro:retailcrm для bitrix:sale.order.ajax является копией .default intaro:sale.order.ajax.
Данные, генерируемые в момент загрузки компонента:
$arResult['LOYALTY_STATUS'] - Включена ли программа лояльности
$arResult['PERSONAL_LOYALTY_STATUS'] - Участвует ли покупатель в программе лояльности
$arResult['CHARGERATE'] - Курс бонуса к валюте CRM системы, установленный в настройках программы лояльности
$arResult['TOTAL_BONUSES_COUNT'] - Всего бонусов на счете (доступных для списания)
$arResult['LP_CALCULATE_SUCCESS'] - Успешно ли выполнен запрос на расчет бонусов
$arResult['WILL_BE_CREDITED'] - Будет начислено бонусов
$arResult['BONUS_CURRENCY'] - Название валюты
$arResult['AVAILABLE_BONUSES'] - Максимально количество бонусов, которые можно потратить
API программы лояльности
В данном разделе описаны методы, которые могут быть использованы для создания собственных или редактирования имеющихся компонентов с функциями программы лояльности.
Контроллеры
В модуле контроллеры расположены в пространстве Intaro\RetailCrm\Controller. Их можно найти по пути bitrix/modules/intaro.retailcrm/lib/controller.
Принцип работы
Подробные сведения о контроллерах представлены в документации 1С-Битрикс.
Контроллеры представляют из себя методы, к которым можно обратиться из внешней среды (например с помощью JavaScript).
Пример обращения к контроллеру:
BX.ajax.runAction('intaro:retailcrm.api.loyalty.basket.calculateBasketBonuses',
{
method: 'POST',
data: {
sessid: BX.bitrix_sessid(),
basketData: result.BASKET_DATA
},
}
).then((response)=>{
//обработка ответа
})
Обратите внимание, что в свойстве data содержится объект, названия свойств которого должны соответствовать названиям аргументов метода, который вызывается. Исключение составляет sessid.
Например, если у метода calculateBasketBonusesAction есть аргумент basketData:
public function calculateBasketBonusesAction(array $basketData): array
то для того чтобы этот аргумент был передан из js, нужно передать
data: {
basketData: //значение
}
Адрес контроллера
Рассмотрим адрес intaro:retailcrm.api.loyalty.basket.calculateBasketBonuses, который вызывает метод calculateBasketBonusesAction у класса Intaro\RetailCrm\Controller\Loyalty\Basket.
intaro- разработчик модуляretailcrm- название модуляapi- псевдоним неймспейса контроллеров \Intaro\RetailCrm\Controller, указанный в intaro.retailcrm/.settings.phployalty- поддиректория в директории controllers, часть namespace класса Basketbasket- название классаcalculateBasketBonuses- название метода, но без слова Action в конце
По этому шаблону можно обратиться к любому из контроллеров.
Каким методом обращаться - POST или GET - можно посмотреть в методе configureActions класса контроллера. Если этого метода нет или в нем нет описания для запроса, то по умолчанию используется метод POST.
Спецификация контроллеров
Класс Intaro\RetailCrm\Controller\Loyalty\Basket:
Название метода: addLoyaltyToBasketAction
Описание метода: Добавляет в массив корзины данные, полученные при расчете привилегии, в массив корзины.
Параметры:
Входные
array $basketData - массив, содержащий информацию о корзине покупателя, который можно получить, например, вызовом CBitrixBasketComponent->getBasketItems();
Выходные
array - Возвращает модифицированную корзину.
Класс Intaro\RetailCrm\Controller\Loyalty\Order:
Название метода: loyaltyCalculateAction
Описание метода: Возвращает результат расчета привилегий программы лояльности.
Параметры:
Входные
array $basketItems - массив корзины
float|int $inputBonuses - количество бонусов для списания
Выходные
null|LoyaltyCalculateResponse (объект является ответом на calculate)
Название метода: sendVerificationCodeAction
Описание метода: Отправляет код верификации из SMS
Параметры:
Входные
$verificationCode - Проверочный код из SMS
$orderId - id заказа
$checkId - Идентификатор проверки кода
Выходные
array(
‘status’ => ‘success/error’
'msg' => string
)
Название метода: resendOrderSmsAction
Описание метода: Повторно отправляет SMS с кодом верификации
Параметры:
Входные
int $orderId - id заказа
Выходные
bool|Intaro\RetailCrm\Model\Bitrix\SmsCookie
Класс Intaro\RetailCrm\Controller\Loyalty\Register:
Название метода: saveUserLpFieldsAction
Описание метода: Сохраняет информацию о регистрации пользователя в программе лояльности в профиле пользователя
Параметры:
Входные
array $request
Выходные
array(
'result' => bool,
'msg' => string
)
Название метода: accountCreateAction
Описание метода: Создает в CRM участие в программе лояльности на основе регистрационных данных
Параметры:
Входные
array $request
Выходные
array(
‘status’ => ‘success/error’
'msg' => string
)
Название метода: resendRegisterSmsAction
Описание метода: Повторно отправляет смс для активации участия в программе лояльности
Параметры:
Входные
string $idInLoyalty - id участия в программе лояльности
Выходные
string[]|null
Название метода: activateLpBySmsAction
Описание метода: Активирует участие в программе лояльности по коду из SMS
Параметры:
Входные
$verificationCode - Проверочный код из SMS
$checkId - Идентификатор проверки кода
Выходные
array(
‘status’ => ‘success/error’
'msg' => string
)
Сервисы
Сервисы располагаются в пространстве имен Intaro\RetailCrm\Service и доступны по адресу bitrix/modules/intaro.retailcrm/lib/service.
Примечание
Обращаться к сервисам рекомендуется через ServiceLocator. Пример:
ServiceLocator::get(LoyaltyService::class);.
Сервисы могут оказаться полезными в тех случаях, когда функционала контроллеров недостаточно.
Спецификация сервисов
LoyaltyAccountService
Названия методов:
activateLoyaltyAccountcreateLoyaltyAccountactivateLpUserInBitrixconfirmVerificationgetLoyaltyPersonalStatuscheckRegInLptryActivate
LoyaltyService
Название метода: sendBonusPayment
Описание метода: Выполняет запрос на применение бонусов по программе лояльности
Параметры:
Входные
int $orderId - ID заказа
int $bonusCount - количество бонусов для списания
Выходные
OrderLoyaltyApplyResponse
Название метода: getLoyaltyCalculate
Описание метода: Возвращает расчет привилегий на основе корзины и количества бонусов для списания. Ответом являет результат выполнения соответствующего метода.
Параметры:
Входные
array $basketItems - корзина
float $bonuses - количество бонусов для списания
Выходные
?LoyaltyCalculateResponse
Название метода: getLoyaltyAccounts
Описание метода: Метод возвращает список участий в программе лояльности. Возвращает первый объект из массива объектов LoyaltyAccount из ответа на запрос.
Параметры:
Входные
int $idInLoyalty - ID участия в программе лояльности
Выходные
?LoyaltyAccount
Названия методов:
resendBonusPaymentsetDebitedStatusaddLoyaltyToBasketcalculateOrderBasketsaveDiscountsgetInitialDiscountisBonusDebitedapplyBonusesInOrder
OrderLoyaltyDataService
Название метода: addCustomersLoyaltyFields
Описание метода: Создает для заказа два пользовательских поля для каждого типа плательщика: «Бонусов начислено» и «Персональная скидка».
Название метода: createLoyaltyHlBlock
Описание метода: Создает HL «Программа лояльности»
Название метода: saveBonusAndDiscToOrderProps
Описание метода: Добавляет информацию о списанных бонусах и скидках программы лояльности в свойства заказа
Параметры:
Входные
\Bitrix\Sale\PropertyValueCollectionBase $props - свойства заказа
float|null $loyaltyDiscountInput - размер скидки по программе лояльности
float|null $loyaltyBonus - количество списанных бонусов по программе лояльности
Название метода: updateLoyaltyInfo
Описание метода: Обновляет данные о начисленных бонусах и скидках в полях заказа
Параметры:
Входные
int $orderId - ID заказа
Название метода: saveLoyaltyInfoToHl
Описание метода: Записывает данные о программе лояльности в HL-блок
Параметры:
Входные
OrderLoyaltyData[] $loyaltyHls - массив объектов записей. Формированием массива занимается Intaro\RetailCrm\Component\Builder\Bitrix\LoyaltyDataBuilder
Обработчики событий
Обработчики располагаются в пространстве имен Intaro\RetailCrm\Component\Handlers по адресу intaro.retailcrm/lib/component/handlers/eventshandlers.php.
OnAfterUserRegisterHandler
Обработчик события OnAfterUserRegister. Регистрирует пользователя в CRM системе после регистрации на сайте.
OnSaleOrderSavedHandler
Обработчик события OnSaleOrderSaved, вызываемого ПОСЛЕ сохранения заказа. Отвечает за сохранение заказа в CRM (если в заказе есть скидки или бонусы программы лояльности, то передает информацию о них).
OnSaleComponentOrderResultPreparedHandler
Обработчик события OnSaleComponentOrderResultPrepared, вызываемого при обновлении еще не сохраненного заказа. Если программа лояльности включена, то модифицирует данные $arResult с учетом привилегий покупателя.
OnAdminContextMenuShowHandler
Обработчик события OnAdminContextMenuShow. Обновляет информацию о программе лояльности в административной панели. При каждом открытии заказа делает запрос к CRM и получает актуальную информацию.