Подключение сайта на MODX к Октопус CDP
Статья описывает подключение интернет-магазина на MODX Revolution с miniShop2 к Октопус CDP: установка пакета, ввод API-ключа, счётчик и первая выгрузка данных.
Шаги выполняются в двух местах: в мастере создания проекта на платформе Октопус CDP и в административной панели (менеджере) MODX.
Первый шаг мастера - URL, название, часовой пояс и PIN-код администратора - описан в статье Создание нового проекта.
Что нужно на сайте:
- MODX Revolution 2.6 или новее;
- miniShop2 2.4 или новее;
- PHP 7.2 или новее с расширениями curl и openssl (на обычном хостинге они уже есть).
1. Установите пакет на сайт
На шаге выбора платформы укажите MODX. На следующем шаге нажмите «Скачать» - скачается файл пакета вида octopuscdp-0.1.11-pl.transport.zip (цифры - номер версии). Не переименовывайте его: по имени файла MODX определяет версию пакета.
Откройте менеджер MODX и перейдите в раздел:
Приложения → Установщик
Нажмите стрелку рядом с кнопкой «Загрузить пакеты» и выберите «Загрузить пакет». Укажите скачанный файл и загрузите его.
Пакет octopusCDP появится в списке. Нажмите в его строке «Установить» и подтвердите установку. После установки в меню «Приложения» появится пункт «Октопус CDP».
Вернитесь на платформу Октопус CDP и нажмите «Дальше».
2. Введите API-ключ
На экране мастера нажмите «Копировать», чтобы скопировать API-ключ проекта.
В менеджере MODX откройте Приложения → Октопус CDP, вставьте ключ в поле «Подключение» и нажмите «Сохранить ключ».
Ключ сразу проверяется. При успехе на странице появится надпись «связь есть» и название вашего проекта. Если ключ не подошёл, появится сообщение об ошибке:
- «Ключ не найден» - ключ скопирован не полностью или от другого проекта;
- «Проект не принимает данные» - проект создан в режиме «Только рассылки».
Вернитесь в мастер и нажмите «Дальше» - Октопус проверит, что ключ получен.
3. Счётчик
Счётчик пакет вставляет на все страницы сайта сам, менять шаблоны не нужно. Достаточно вернуться в мастер и нажать «Дальше»: Октопус откроет главную страницу сайта и проверит, что счётчик на месте.
Если автоматическая вставка не подходит (например, счётчик нужен только в части разделов), выключите её в системной настройке octopuscdp.tracking_auto_insert и вставьте в нужные шаблоны перед закрывающим тегом </body>:
[[!OctopusCdpTracker]]
После проверки счётчика мастер сообщит, что проект создан. Нажмите «Перейти к проекту».
4. Выгрузите клиентов, каталог и заказы
Новые клиенты, заказы, товары, визиты и изменения корзины передаются в Октопус сами по мере появления. Историю, которая накопилась до подключения, нужно выгрузить один раз. Для нового проекта выгрузка начинается сама сразу после сохранения ключа - за ней можно следить на странице пакета.
Чтобы запустить выгрузку вручную, откройте в менеджере MODX Приложения → Октопус CDP, блок «Первичная выгрузка», и нажимайте «Запустить» по порядку, дожидаясь надписи «готово»: «Клиенты», «Разделы каталога», «Товары», «Заказы».
Порядок важен: заказ привязывается к клиенту и товарам, поэтому они должны прийти раньше. Каталог на десятки тысяч товаров выгружается 15-20 минут. Страницу не закрывайте, пока идёт выгрузка. Если закрыли - откройте снова и нажмите «Продолжить», выгрузка пойдёт с того места, где остановилась.
Сценарии по историческим заказам при выгрузке не запускаются: события «Новый заказ», «Оплата заказа» и другие события заказов запускают сценарии, только если заказ оформлен (оплачен, отменён) не раньше чем за сутки до выгрузки.
5. Сопоставьте поля клиентов и товаров
При первом открытии проекта запустится синхронизация клиентов, а затем этап сопоставления полей.
Подробнее - в статье Синхронизация клиентов и сопоставление полей.
Товары появятся в Октопусе после того, как вы сопоставите их поля: Настройки → Коннекторы → коннектор MODX → Товарные поля. Поля приходят под именами MODX и miniShop2:
| Поле Октопуса | Поле сайта |
|---|---|
| Название | pagetitle |
| URL страницы товара | url |
| URL картинки | image (большая) или thumb (превью) |
| Цена | price |
| Старая цена (без скидки) | old_price |
| Валюта | currency |
Кроме них доступны article, weight, vendor, made_in, longtitle, опции miniShop2 и дополнительные поля товара (TV) - под своими именами. Если старой цены у товара нет, в old_price передаётся его цена.
Какие данные передаются
| Данные | Что входит |
|---|---|
| Клиенты | E-mail, имя, телефоны, адрес, дата рождения, пол, группы пользователя, дата регистрации и последнего входа, простые дополнительные поля профиля |
| Каталог | Разделы и товары miniShop2: название, ссылка, картинка, цены, артикул, производитель, опции и дополнительные поля. Товар без цены считается «нет в наличии»: он остаётся в каталоге и в истории визитов, но не попадает в рекомендации и подборки. Если товары без цены у вас заказывают («цена по запросу»), включите настройку octopuscdp.product_unpriced_available. Изменения в админке уходят сразу, изменения мимо неё (например, обменом с 1С) - в течение получаса |
| Заказы | Номер, клиент, состав, суммы, статус, доставка, способ оплаты, отметки «оплачен» и «отменён» |
| Визиты | Адрес страницы, источник перехода, UTM-метки, устройство и браузер |
| Корзина | Текущее содержимое корзины - на нём работают сценарии брошенной корзины |
| Цели | Клики по кнопкам и отправки форм, настроенные в разделе целей, и цели, которые сайт вызывает сам. Подробнее - ниже |
| Переходы из рассылок | Клиент, перешедший по ссылке из письма Октопуса, опознаётся на сайте ещё до входа в аккаунт |
Посетитель, который вошёл в аккаунт или оформил заказ, связывается с карточкой клиента вместе со всей историей визитов.
Цели
Цели создаются на платформе Октопус CDP - как их настроить, описано в статье Создание цели. Сайт получает новые и изменённые цели сам, примерно за минуту; список целей виден на странице Приложения → Октопус CDP, блок «Цели».
Кнопка. Цель засчитывается при клике по элементу с указанным id - и по любому элементу внутри него, например иконке в кнопке.
Форма. Цель засчитывается при отправке формы с указанным id (или формы внутри блока с этим id). Значения полей, которые выбраны в настройках цели, передаются в Октопус: по ним клиент опознаётся, а поля с отметкой «обновлять» записываются в его карточку.
Когда именно засчитывается форма, зависит от того, как она отправляется:
| Как отправляется форма | Когда засчитывается цель |
|---|---|
| Через AjaxForm (FormIt) | После ответа сайта и только при успешной отправке - форма с ошибкой в полях цель не даст |
| Обычная отправка с перезагрузкой страницы | В момент нажатия кнопки отправки |
| Своим скриптом, без отправки формы | Не засчитывается - вызовите цель из скрипта, как описано ниже |
Кнопки и формы, которые появляются на странице позже - во всплывающих окнах или после подгрузки, - тоже отслеживаются.
Страница цели. Если в цели указана страница, сравниваются домен и путь: /contacts/ и https://site.ru/contacts - одна страница, слэш на конце и #якорь не важны. Параметры, указанные в адресе цели, должны быть и на странице: цель с адресом /catalog/?type=bolt не сработает на /catalog/?type=nut. Остальные параметры - метки рекламы и рассылок (utm_source и другие) - не мешают.
Цель из своего скрипта
Если форма или кнопка работают на своём скрипте - например, это форма Битрикс24 или другого сервиса, - создайте цель типа «JavaScript-событие» и вызовите её из скрипта функцией oct_goal. Функция есть на всех страницах с установленным пакетом, её можно вызывать в любой момент, даже до полной загрузки страницы.
oct_goal('price_list'); // price_list - идентификатор цели
Чтобы вместе с целью записать данные в карточку клиента, передайте их в объекте update. Ключи - коды полей клиента из раздела Настройки → Поля клиентов:
oct_goal('price_list', {
update: {
NAME: 'Иван',
EMAIL: 'ivan@example.ru',
PERSONAL_PHONE: '+7 999 123-45-67'
}
});
- Если посетитель уже известен (вошёл на сайт, оформлял заказ или пришёл по ссылке из письма), поля обновятся в его карточке.
- Если нет - Октопус найдёт клиента по
EMAILилиPERSONAL_PHONE, а если не найдёт, заведёт новую карточку. Прошлые визиты и цели посетителя переносятся в неё. Без e-mail и телефона карточка не заводится: цель запишется на посетителя и попадёт в карточку, когда он войдёт на сайт или оформит заказ. - Ключи - именно коды полей Октопуса, а не имена полей формы или MODX (
fullname,phone): значения записываются в карточку напрямую, без сопоставления полей. - Поля, которых нет в
update, не меняются. Пустые значения лучше не передавать.
Для формы Битрикс24 или другого сервиса вызывайте oct_goal в обработчике успешной отправки формы - тогда цель не засчитается за неотправленную заявку. Как подключить такой обработчик, описано в документации сервиса формы; обычно это делает разработчик сайта.
Настройки пакета
Настройки находятся в Управление → Системные настройки, пространство имён octopuscdp.
| Настройка | Назначение |
|---|---|
octopuscdp.paid_statuses | Статусы miniShop2, при которых заказ считается оплаченным. По умолчанию 2 («Оплачен»). Заказ, хотя бы раз побывавший в таком статусе, остаётся оплаченным |
octopuscdp.canceled_statuses | Статусы «отменён». По умолчанию 4 |
octopuscdp.currency | Валюта заказов и товаров, по умолчанию RUB |
octopuscdp.product_quantity_tv | Дополнительное поле (TV) с остатком товара. Если задано, товар считается в наличии, только когда остаток больше нуля; если пусто - в наличии любой опубликованный товар с ценой |
octopuscdp.product_unpriced_available | Товар без цены в наличии. Включите, если цена 0 у вас означает «цена по запросу» и такие товары заказывают. Если выключено (по умолчанию), товар без цены передаётся «нет в наличии» |
octopuscdp.product_image_from_showcase | Для товаров без своей картинки брать картинку товара-витрины из того же раздела (товар без цены, у которого картинка есть). Подходит магазинам, где размеры или фасовки заведены отдельными товарами без фото, а фото есть у общей страницы товара. По умолчанию выключено |
octopuscdp.tracking_auto_insert | Вставлять счётчик на страницы автоматически |
octopuscdp.allowed_hosts | Дополнительные домены, с которых принимаются визиты (поддомены сайта разрешены всегда) |
octopuscdp.ip_header | Заголовок с реальным IP посетителя, если сайт за защитой от DDoS или CDN, например X-Forwarded-For |
octopuscdp.user_extended_skip | Дополнительные поля профиля, которые не нужно передавать |
octopuscdp.enabled | Временно остановить передачу данных, не удаляя ключ |
miniShop2 не хранит отдельной отметки об оплате - пакет определяет её по статусу заказа. Если ваш магазин не переводит заказы в статус «Оплачен» (например, оплата ведётся в 1С или CRM), заказы попадут в Октопус неоплаченными, и выручка по ним считаться не будет. Укажите в octopuscdp.paid_statuses статусы, которые у вас означают оплату.
Отправка данных и cron
Данные копятся в очереди на сайте и уходят в Октопус пачками, после ответа посетителю - на скорость страниц это не влияет. Если Октопус временно недоступен, пакет повторит отправку позже.
Очередь обслуживается при посещениях сайта. Если посещаемость небольшая, добавьте на хостинге задание cron раз в минуту:
php /путь/к/сайту/core/components/octopuscdp/cron.php
Состояние очереди и последние ошибки видны на странице Приложения → Октопус CDP.
Клиенты и заказы, которые Октопус не принял
Бывает, что данные дошли до Октопуса, но клиента или заказ завести нельзя: например, у клиента на сайте записан e-mail с ошибкой. Такие случаи пакет собирает в журнал. Если он не пуст, в блоке «Очередь отправки» появляется строка «Не приняты Октопусом: N — посмотреть». По ссылке открывается таблица:
| Колонка | Что в ней |
|---|---|
| Что | Клиент или заказ |
| Номер на сайте | ID в MODX; у клиента - ссылка на его карточку в менеджере |
| Причина | Почему Октопус не завёл запись |
| Последний раз | Когда пришёл последний отказ |
Частые причины:
- «Неверный email» - исправьте e-mail в карточке клиента на сайте.
- «Клиент ещё не передан — заказ будет проведён, когда клиент появится» - заказ ждёт карточку своего клиента. Обычно это заказ клиента, которого Октопус не принял (смотрите строку этого клиента выше) или который удалён на сайте. Когда клиента примут, заказ проведётся сам.
После исправления запись уходит из журнала сама при следующей отправке клиента или заказа. Чтобы не ждать, запустите в «Первичной выгрузке» повторную выгрузку клиентов (и заказов) - дублей не будет. Записи старше 30 дней удаляются.
Обновление пакета
Новые версии пакета приходят прямо в MODX - скачивать их вручную не нужно. После ввода API-ключа пакет добавляет в Установщик поставщика пакетов «Октопус CDP». Когда выходит новая версия, в строке пакета OctopusCDP появляется кнопка «Обновить»: нажмите её и подтвердите установку. Настройки, ключ и данные очереди при обновлении сохраняются.
Если кнопки нет, нажмите в строке пакета «Проверить обновления». MODX проверяет обновления не чаще раза в 15 минут.
В этих версиях обновления через Установщик ещё нет. Обновите пакет один раз вручную: попросите файл новой версии у поддержки Октопуса, загрузите его в Установщике так же, как при установке (имя файла не меняйте), и нажмите «Установить». Дальше обновления будут приходить сами.
Что пока не поддерживается
Для сайтов на MODX пока недоступны: промокоды, всплывающие окна и программа лояльности. Торговые предложения (варианты товара) пакет передаёт как отдельные товары.