Интеграция интернет-магазина на 1С-Битрикс с Mindbox
Для развития систем лояльности интернет-магазины обращаются к платформам автоматизации маркетинга, Customer Data Platform (CDP). При этом иногда для успешной интеграции нужно сохранять больше данных, чем указано в документации к API.
Рассказываем, какие данные понадобились нам для интеграции магазина на «1С-Битрикс» с платформой Mindbox, как их можно получить с помощью API и SDK и как использовать комбинированный подход с асинхронной отправкой данных.
С помощью сервисов Customer Data Platform ритейлеры «узнают» портрет своего покупателя, в том числе поведенческие данные. Эта информация хранится в CDP в защищенном виде и помогает ритейлерам в проведении маркетинговых кампаний и аналитике.
Когда покупатель добавляет в корзину телевизор или любой другой товар, CDP сохраняет эти данные. На их основе ритейлеры получают возможность расширить свое взаимодействие с пользователями, например предложить рекомендации и скидки на похожие товары.
Один из наших клиентов — сеть магазинов электроники — принял решение подключиться к CDP-платформе Mindbox и обратился к нам за помощью в интеграции. Мы проводили интеграцию по ключевым пользовательским сценариям: авторизация, добавление в корзину, оплата и др.
Предыстория
Интернет-магазины могут подключиться к Mindbox двумя основными способами: с помощью API либо JavaScript SDK (об отличиях мы расскажем далее).
Для выбора оптимального способа мы обратились к документации Mindbox, а если информации не хватало, то задавали вопросы менеджеру. Мы выяснили, что наше сотрудничество совпало с периодом бурного роста платформы Mindbox: среднесуточная нагрузка по вызовам API Mindbox увеличилась вдвое (до 120 тысяч запросов в минуту, в пик — до 250 тысяч). Это означало, что в период Черной пятницы и прочих распродаж из-за дополнительного роста нагрузки возникал риск, что CDP-сервис окажется недоступен и не получит данные интернет-магазина, который с ним интегрирован.
Mindbox быстро отреагировал на эту проблему и начал улучшать архитектуру и инфраструктуру своих IT-систем, чтобы добиться четырехкратного запаса прочности. Нам, в свою очередь, нужно было обеспечить бесперебойную отправку в Mindbox данных о покупках. Для этого требовалось выбрать самый надежный способ интеграции.
Методы интеграции с Mindbox
Как отмечено выше, Mindbox предлагает использовать для подключения API или JavaScript SDK. Далее рассмотрим их особенности.
JavaScript SDK
Ограничения: возможна потеря данных, если Mindbox недоступен в момент отправки. Скрипты платформы не подгрузятся, если на стороне интернет-магазина есть js-ошибки.
Интеграция по API
Ограничения: мы столкнулись с тем, что не получали некоторые данные cookie, а именно уникальный идентификатор пользователя на устройстве (mindboxDeviceUUID). Его необходимо передавать в большинстве операций Mindbox для склеивания информации по пользователю.
В документации эти cookie обязательны не для всех операций. И всё же, стремясь к бесперебойной передаче данных, мы обсудили этот вопрос с менеджером Mindbox. Выяснили, что для максимальной надежности желательно всегда отправлять cookie. При этом для получения cookie нужно использовать JavaScript SDK.
Комбинированный метод
Мы рассмотрели описанные выше способы интеграции, но в чистом виде они не подходили для нашего проекта. Для решения бизнес-задач ритейлера и построения системы лояльности нужно было передавать в Mindbox полный набор данных о действиях пользователей, включая идентификатор из cookie. Одновременно с этим мы стремились снизить зависимость от JavaScript и риски потери данных в случае временной недоступности Mindbox.
Поэтому мы обратились к третьему, комбинированному методу: работаем и с API, и с JavaScript SDK, используя наш модуль очередей.
С помощью Javascript SDK мы идентифицируем пользователя на сайте (mindboxDeviceUUID). Затем на стороне сервера формируем запрос со всеми необходимыми данными и помещаем его в очередь. Запросы из очереди через API отправляются сервису Mindbox. В случае отрицательного ответа запрос повторно помещается в очередь. Таким образом, при отправке данных Mindbox получает полный комплект необходимой информации.
В приведенном далее примере класс Sender позволяет собрать и отправить запрос, выполнив первичную обработку ответа. Класс использует данные из самой команды (тип запроса/ответа, deviceUUID и др.) и из настроек модуля (параметры работы с API, токены и т.п.).
Трейт Sendable содержит все возможные настройки команды для отправки запроса в Mindbox, в том числе предустановленные, такие как тип запроса/ответа, метод запроса и параметр синхронности/асинхронности. Также в нем присутствуют методы, общие для всех команд.
В качестве примера рассмотрим событие авторизации пользователя. В обработчике события авторизации мы добавляем в нашу очередь объект класса AuthorizationCommand. В этом классе происходит минимально необходимая подготовка информации, поскольку в момент выполнения команды данные в базе могут измениться, и нужно их сохранить. Также устанавливаются соответствующие параметры для запроса в Mindbox, в данном случае это название операции (узнаем в админ. панели Mindbox). Дополнительно можно указать тип запроса/ответа, метод запроса и параметр синхронности/асинхронности согласно трейту Sendable.
Схема взаимодействия модулей
В нашем проекте мы выделили три модуля:
Базовый
Модуль очередей
Модуль интеграции с Mindbox

Модуль Mindbox отслеживает на сайте события и сопутствующую информацию, в том числе из cookie, формирует из них команду и помещает её в очередь. Когда модуль очередей извлекает команду из очереди и выполняет её, происходит отправка данных. Если ответ от Mindbox отрицательный — неудачно выполненная команда переносится в конец очереди, если положительный — успешно выполненная команда удаляется из очереди.
Таким образом, с помощью описанного выше комбинированного метода мы смогли обеспечить бесперебойную передачу данных в Mindbox.
Подводя итоги
В этой статье мы рассмотрели, какими способами интернет-магазин может подключиться к Customer Data Platform для развития систем лояльности.
В нашем примере в документации Mindbox были описаны два основных способа подключения: через Javascript SDK и через API. Для повышения надежности передачи данных, даже в случае временной недоступности CDP-сервиса, мы выбрали и реализовали третий, комбинированный способ: с помощью API и Javascript SDK, с асинхронной отправкой данных.
Как вызвать веб сервис mindbox
Вебхук — это механизм, с помощью которого можно вызывать произвольные http -сервисы при наступлении определённых событий.
Более простым языком — механизм оповещения системы о событиях.
- Вебхук нужен для передачи информации от mindbox к внешней системе
- Инициатором в отправке вебхука выступает mindbox
- ТЗ на вебхук подготавливается заказчиком
- Вебхук используется в шаге сценария
Например, его можно использовать для:
— отправки в call центр информации о новом заказе или его изменение
— оповещения персонала о негативной оценке клиента
— синхронизировать подписки
— и т.д.
Вариантов использования гораздо больше, инструмент достаточно гибкий.
Верхнеуровнево вебхук состоит из трех частей:
— адрес, к которому он обращается
— заголовки (отвечают за метод/авторизацию и тд.)
— тело (данные, которые мы передаем)
Создание вебхука
Управление вебхуками находится в меню Интеграции —> Вебхуки

Для создания нового вебхука нажмите кнопку «Добавить»:
- Имя — название вебхука, которое отобразится в настройках сценария.

- Метод — выбираем в зависимости от задачи: GET, POST или PUT
Более подробно почитать о методах можно здесь.

- Прописываем URL — адрес, к которому будет обращаться вебхук. Формируется на стороне заказчика, можно предложить шаблонный по нашему образцу
пример итогового URL

Если добавить параметр $ в адрес, заголовок или тело запроса, то параметр будет присваивать ID запросу вебхука.
Вебхук будет повторно подключаться в течение 3 дней, пока не отработает успешно (код 200).
Если этого параметра нет — повторных попыток подключения не произойдет.
Например:в базу попал новый адрес почты и мы хотим передать его во внешнюю систему (id запроса = 1), но в момент передачи произошла ошибка и запрос не отработал.
Без TransactionalId внешняя система не знает, был ли такой запрос или нет. В итоге мы не можем его повторить (ведь все запросы без идентификаторов, как отличить один от другого), в итоге данные потеряны.
С TransactionalId внешняя система смотрит и видит, что вебхука с id 1 еще не было, а значит это новые данные, их нужно сохранить.
Итог — данные не потеряны
- Заполняем заголовки — заголовков может быть несколько:

- Заполняем тело запроса для метода POST — в теле запроса можно перечислить любые параметры из системы, доступен код JSON, поэтому условия (if) допускаются

Доступна Справка по шаблонизатору, если есть сомнения в названии полей
- Нажимаем на кнопку «Сохранить изменения»

Ошибки, где смотреть
При работе вебхука могу возникать ошибки, некоторые из них можно посмотреть в интерфейсе.
Нажимаем на значок «молнии» в нижнем левом углу:

В проблеме отображается название вебхука, ошибка с ID клиента и ссылка на ошибочные события.
Что такое вебхуки и как они используются, где их можно настроить, примеры использования в Mindbox.
Как вызвать веб сервис mindbox
POST https://api.mindbox.cloud/v3/o. n=get.user
Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Mindbox secretKey=»OrR5saKsiraMt1vei5Mw»
Host: api.mindbox.ru
«customer»: «email»: «mikanev@mindbox.ru»
>
>
Вызов WCF сервиса
Добрый день. Скажу сражу что сервисы я начал изучать недавно Передо мной такая задача. в.
Выхлоп веб-сервиса
Привет всем. Есть веб сервис (сделан на VisualStudio2005, язык C#), принимает несколько строк.
Как вызвать веб сервис mindbox
- Вебхук нужен для передачи информации от mindbox к внешней системе
- Инициатором в отправке вебхука выступает mindbox
- ТЗ на вебхук подготавливается заказчиком
- Вебхук используется в шаге операции или триггера

- Имя — название вебхука, которое отобразится в настройках операции или триггера

- Метод — выбираем в зависимости от задачи: GET, POST или PUT
Более подробно почитать о методах можно здесь .

- Прописываем URL — адрес, к которому будет обращаться вебхук. Формируется на стороне заказчика, можно предложить шаблонный по нашему образцу

- Заполняем заголовки — заголовков может быть несколько:

- Заполняем тело запроса для метода POST — в теле запроса можно перечислить любые параметры из системы, доступен код JSON, поэтому условия (if) допускаются

- Нажимаем на кнопку «Сохранить изменения»


Как вызвать веб сервис mindbox
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
- method — HTTP метод запроса: ‘POST’, ‘GET’;
- operationName — название операции в Mindbox;
- body — тело запроса в виде DTO, необязательный параметр;
- additionalUrl — дополнительный URL, конкатенируется с базовым URL: https://api.mindbox.ru/v3/operations/ , необязательный параметр;
- queryParams — массив дополнительных GET параметров, необязательный параметр;
- isSync — флаг, синхронный или асинхронный запрос, по умолчанию true (синхронный), необязательный параметр;
- addDeviceUUID — флаг, добавлять ли DeviceUUID в запрос, по умолчанию true (добавляет DeviceUUID из куки mindboxDeviceUUID в query-параметры запроса и IP-адрес потребителя в заголовок X-Customer-IP), необязательный параметр.
Footer
© 2022 GitHub, Inc.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Name already in use
php-sdk / docs / structure / Mindbox-Helpers-CustomerHelper.md
- Go to file T
- Go to line L
- Copy path
- Copy permalink
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
Хелпер, являющий обёрткой над универсальным запросом. Содержит методы для отправки запросов, связанных с действиями над потребителем.
- Class name: CustomerHelper
- Namespace: Mindbox\Helpers
- Parent class: Mindbox\Helpers\AbstractMindboxHelper
- Visibility: protected
Выполняет вызов стандартной операции Website.AuthorizeCustomer:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.CheckCustomerByMobilePhone:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.CheckCustomerByEmail:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.RegisterCustomer:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.EditCustomer:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.FillCustomerProfile:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.GetCustomerDataByDiscountCard:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.MergeCustomers:
- Visibility: public
- $customersToMerge Mindbox\DTO\V3\Requests\MergeCustomersRequestDTO — <p>Объект, содержащий данные объединяемых потребителей для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.CheckCustomerIsInLoyalityProgram:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.GetCustomerBonusPointsHistory:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $page Mindbox\DTO\V3\Requests\PageRequestDTO — <p>Объект, содержащий данные пагинации для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.SendMobilePhoneAuthorizationCode:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
- $isSync boolean — <p>Флаг, сообщающий о необходимости выполнять запрос синхронно/асинхронно.</p>
Выполняет вызов стандартной операции Website.CheckMobilePhoneAuthorizationCode:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $authentificationCode string — <p>Код аутентификации.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.ResendMobilePhoneConfirmationCode:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
- $isSync boolean — <p>Флаг, сообщающий о необходимости выполнять запрос синхронно/асинхронно.</p>
Выполняет вызов стандартной операции Website.ConfirmMobilePhone:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $smsConfirmation Mindbox\DTO\V3\Requests\SmsConfirmationRequestDTO — <p>Объект, содержащий код подтверждения.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
- $isSync boolean — <p>Флаг, сообщающий о необходимости выполнять запрос синхронно/асинхронно.</p>
Выполняет вызов стандартной операции Website.SubscribeCustomer:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
- $isSync boolean — <p>Флаг, сообщающий о необходимости выполнять запрос синхронно/асинхронно.</p>
Выполняет вызов стандартной операции Website.AutoConfirmMobilePhone:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
Выполняет вызов стандартной операции Website.GetCustomerBalance:
- Visibility: public
- $customer Mindbox\DTO\V3\Requests\CustomerRequestDTO — <p>Объект, содержащий данные потребителя для запроса.</p>
- $operationName string — <p>Название операции.</p>
- $addDeviceUUID boolean — <p>Флаг, сообщающий о необходимости передать в запросе DeviceUUID.</p>
- Visibility: public
- This method is defined by Mindbox\Helpers\AbstractMindboxHelper
- $client Mindbox\Clients\AbstractMindboxClient — <p>Экземпляр клиента Mindbox.</p>
Инициализация объекта OperationDTO.
- Visibility: protected
- This method is defined by Mindbox\Helpers\AbstractMindboxHelper
Возвращает экземпляр последнего ответа от Mindbox.
- Visibility: public
- This method is defined by Mindbox\Helpers\AbstractMindboxHelper
- Visibility: public
- This method is defined by Mindbox\Helpers\AbstractMindboxHelper
- Visibility: public
- This method is defined by Mindbox\Helpers\AbstractMindboxHelper
Footer
© 2023 GitHub, Inc.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.