Модуль 1С-Битрикс¶

Модуль Ziex Try-On — виртуальная примерка (код модуля ziex.tryon) добавляет кнопку «Примерить» на карточку товара магазина на 1С-Битрикс. Покупатель загружает своё фото и видит вещь на себе.

Текущая версия — 0.1.4. Модуль на раннем этапе (0.1): его передают архивом, для скачивания он не опубликован.

Что делает модуль¶

Выводит кнопку «Примерить» под кнопками покупки на карточке товара и по нажатию запускает виджет.
Связывает сайт с сервисом по вашему секретному ключу. Ключ хранится только в базе данных сайта: его нет ни в HTML страниц, ни в логах.
Кладёт на страницы только публикуемый ключ (pk_…). Модуль получает его от сервиса сам. См. Ключи.
Для каждого товара по его разделам каталога решает, показывать ли кнопку и какого типа эта вещь.
Для товара с цветами и размерами (торговые предложения) примеряет фото выбранного предложения.
Не выводит на страницы встроенных <script>. Асинхронно добавляет лоадер сервиса; скрипт виджета загружается при первом нажатии на кнопку, а на странице, где во вкладке есть незавершённая примерка этого магазина, — сразу.

Кнопка есть только на карточке товара. В списках товаров, окнах быстрого просмотра и карточках, которые подгружаются через AJAX, её нет. Если сайт отвечает на нескольких несвязанных доменах, кнопка работает только на домене, к которому привязан ключ, вместе с www. и поддоменами. Статистики примерок в админке Битрикса нет: история — в клиентском портале на https://app.ziex-tryon.com.

Требования¶


Продукт	1С-Битрикс: Управление сайтом на вашем сервере. Облачный Битрикс24 не поддерживается.
Главный модуль (`main`)	23.0.0 или новее. Проверено на 26.150.0.
PHP	7.4 или новее (7.4–8.x)
Кодировка	UTF-8 (режим UTF-8 в настройках ядра)
Модули	«Информационные блоки» (`iblock`). Желателен модуль торгового каталога (`catalog`).
Права на запись	Папки `/local/components` и `/bitrix/js`. Установщик копирует туда компонент кнопки, скрипт и стили.
Ключ	Боевой секретный ключ (`tryon_…`), привязанный к домену вашего сайта

Фото цветов и размеров (торговые предложения) требуют редакции с интернет-магазином: Малый бизнес, Бизнес или Энтерпрайз. В редакциях Старт и Стандарт работает обычный каталог на инфоблоках.

Ключ выдаём мы. Он показывается один раз, при создании, поэтому сохраните его. Привязка к домену действует и на его вариант с www., и на поддомены. Кириллический домен привязывается в punycode-виде (xn--…): именно в нём модуль отправляет адрес сайта. Сообщите об этом менеджеру при выдаче ключа.

Где взять модуль¶

Архив ziex.tryon-<версия>.zip выдаёт ваш менеджер. Для скачивания он пока не опубликован: у этого модуля в блоке integrations ответа GET /api/v1/tryon/integration стоит download_url: null (см. Создание плагина). Чтобы запросить архив и ключ, см. Контакты.

Установка и подключение¶

Распакуйте архив в папку /local/modules/ сайта (по FTP или SFTP, через панель хостинга или файловый менеджер) так, чтобы существовал файл /local/modules/ziex.tryon/install/index.php. Если /local/modules/ нет, создайте её. Держите модуль в одном месте: пока в /local/modules/ziex.tryon/ лежит копия, Битрикс загружает модуль из неё, и более новая копия в /bitrix/modules/ziex.tryon/ не действует.
В административной части откройте Marketplace → Установленные решения. Битрикс показывает там модули, найденные в /local/modules/. Найдите строку «Ziex Try-On — виртуальная примерка», откройте меню строки и выберите Установить.
Установщик проверяет требования. Если что-то не подходит, он пишет «Модуль Ziex Try-On не установлен» и перечисляет причины: версия PHP, режим UTF-8, модуль «Информационные блоки», версия главного модуля, права на запись в /local/components или /bitrix/js. Устраните причину и установите снова. Пока требования не выполнены, ничего не устанавливается.
Когда всё в порядке, нажмите «Открыть настройки». Страница настроек — Магазин → Виртуальная примерка. На сайте без модуля sale пункт находится в разделе Сервисы.
На вкладке «Подключение» вставьте секретный ключ в поле «Ключ API» и нажмите «Сохранить и проверить». Модуль спросит у сервиса, подходит ли ключ этому сайту. Карточка статуса станет «Подключено» и покажет аккаунт, разрешённый сайт, тариф и остаток генераций.
На вкладке «Каталог и категории» нажмите «Подсказать по названиям», проверьте выбор и нажмите «Сохранить».
Добавьте кнопку в шаблон карточки товара (ниже).
Добавьте в политику конфиденциальности абзац о сервисе. См. Конфиденциальность, CSP и тестовые ключи.

Установка копирует компонент кнопки в /local/components/ziex/tryon.button/, а скрипт и стили — в /bitrix/js/ziex.tryon/, добавляет агент, который раз в час перепроверяет ключ, создаёт свойство товара «Виртуальная примерка» в инфоблоках каталога и добавляет пункт меню. Товары, разделы и шаблоны сайта она не меняет.

Настройки¶

На странице настроек вкладки «Подключение», «Каталог и категории», «Кнопка», «Политика конфиденциальности» и «Доступ». Если в одной установке Битрикса несколько сайтов, сайт выбирается селектором «Сайт:» вверху страницы; каждая настройка хранится отдельно для каждого сайта.

Подключение¶

Настройка	Что делает
Ключ API	Секретный ключ. После сохранения поле пустое, сохранённый ключ показан в маске. Пустое поле при сохранении оставляет сохранённый ключ. Ключ `pk_…` отклоняется с сообщением, что нужен секретный. Ключ, который не `tryon_` и 32–64 букв, цифр или подчёркиваний, тоже отклоняется. При отказе ничего не сохраняется.
Показывать кнопку на сайте	Включено по умолчанию.
Кабинет покупателя («Мои образы»)	Включён по умолчанию. Виджет хранит результаты покупателя в его браузере до 30 дней, а его фото — только если он отметил «Запомнить фото на этом устройстве». Если выключить, то при следующем визите стирается и то, что посетители уже сохранили.
Адрес сайта для проверки	Обычно пусто. Модуль вычисляет адрес по настройкам сайта, и серый текст в поле показывает, какой именно. Заполняйте, только если ключ «привязан к другому сайту» из-за неверно вычисленного адреса. Введите полный адрес вида `https://shop.example.com/`. Сравнивается только имя хоста.
Отладка в консоли браузера	Только для поиска причин. Скрипт модуля пишет в консоль браузера предупреждения о кнопке.
Отключить	Удаляет ключ и статус и скрывает кнопки.

«Сохранить и проверить» спрашивает сервис о ключе, получает публикуемый ключ и показывает результат. Ключ сохраняется только вместе с проверкой. Модуль повторяет проверку каждый час агентом Битрикса.

Отказ по ключу (неверный, отозван, приостановлен, привязан к другому сайту) переводит карточку в «Не подключено» с причиной и убирает кнопки с сайта.
Сетевая ошибка или сбой сервиса кнопки никогда не скрывает. Остаётся последний хороший статус, а карточка показывает время и причину последней проверки. Если сервис не отвечает больше суток, в административной части появляется уведомление.
Если мы перевыпустим публикуемый ключ, виджет не будет работать, пока модуль не проверит ключ снова, — это случится в течение часа. Нажмите «Сохранить и проверить» сразу после замены и оставьте поле «Ключ API» пустым: сохранённый ключ остаётся, а новый публикуемый ключ модуль получит сам.

Каталог и категории¶

Сервис умеет примерять не всё. Вкладка показывает блок «Что можно примерить» (обычно верх, верхняя одежда, низ, платья и комбинезоны) и то, что нельзя (например, обувь и сумки). Список приходит от сервиса и может расти.

«Инфоблоки каталога» по умолчанию выбираются автоматически: это каталоги товаров сайта без инфоблоков торговых предложений. Выберите инфоблоки вручную, если ваши товары лежат в другом месте.

Для каждого раздела каталога (таблица «Раздел», «Товаров», «Примерка») выберите одно значение:

Значение	Смысл
Название категории	Все товары раздела примеряются как вещь этого типа.
Нельзя примерить	У товаров нет кнопки. Если так помечен хотя бы один раздел товара, кнопки у товара нет.
Автоопределение (смешанный раздел)	Тип вещи определяет сервис. Для смешанных разделов вроде «Спорт».
— не влияет	Раздел ничего не решает. Для подборок вроде «Новинки» или «Распродажа». Подраздел, который не влияет, берёт значение родительского.

Если у товара несколько разделов с разными категориями, используется автоопределение, когда сервис его предлагает; иначе кнопки нет. Если ни один раздел товара не задаёт категорию, кнопки тоже нет.

«Подсказать по названиям» заполняет только пустые значения по названиям разделов. Сама по себе кнопка ничего не сохраняет. «Обновить список» сразу забирает у сервиса список категорий. Когда сервис добавляет категорию, уведомление просит проверить сопоставление. «Сохранить» применяет выбор; кнопки на страницах обновляются сами.

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

Выбор на товаре. Свойство товара «Виртуальная примерка» (код ZIEX_TRYON_CATEGORY) важнее разделов. Его значения — «Как в разделе» (по умолчанию), категория, «Автоопределение» и «Не показывать примерку». Установка создаёт свойство в инфоблоках каталога. Если его нет, например у нового инфоблока, нажмите на этой вкладке «Создать свойство «Виртуальная примерка»».

Кнопка¶

Настройка	Что делает
Текст кнопки	Пусто — «Примерить» (или его перевод по языку сайта). Не больше 60 символов.
CSS-классы кнопки	Классы, которые делают кнопку похожей на кнопки вашего шаблона. По умолчанию: `btn u-btn-outline-primary product-item-detail-buy-button`.
Где появляется кнопка	Строкой в шаблоне карточки (рекомендуется) или Автоматически, без правки шаблона.

Какое фото примеряется. У торгового предложения со своим фото при выборе его цвета берётся это фото. Иначе берётся фото товара: детальная картинка, затем картинка анонса, затем первое из дополнительных фото (MORE_PHOTO). Если фото нет ни у выбранного предложения, ни у товара, кнопка скрыта, пока не выбрано предложение с фото. Фото прежнего предложения не подставляется никогда. Если фото нет ни у товара, ни у его предложений, кнопки нет.

Строка в шаблоне карточки¶

Это вариант по умолчанию. Он надёжен и переживает обновления Битрикса. Те же шаги, с путями вашего сайта, показаны на вкладке «Кнопка» рядом со строкой.

Найдите шаблон карточки. Карточку показывает компонент bitrix:catalog.element. В типичном магазине его шаблон bootstrap_v4 лежит в /bitrix/components/bitrix/catalog.element/templates/bootstrap_v4/. Вкладка «Кнопка» называет папку, из которой ваш сайт берёт карточку сейчас.
Скопируйте папку шаблона (файловым менеджером административной части или по FTP) туда, где шаблон вашего сайта ищет в первую очередь:
- Шаблон сайта лежит в /bitrix/templates/ (в большинстве магазинов): скопируйте в /local/templates/.default/components/bitrix/catalog.element/<название шаблона карточки>/.
- Сайт (все страницы или часть) рисуется самим шаблоном сайта .default: скопируйте в /bitrix/templates/.default/components/bitrix/catalog.element/<название шаблона карточки>/. Папка /local/templates/.default/ затенила бы такой шаблон сайта. Если карточка берётся из шаблона каталога /bitrix/components/bitrix/catalog/templates/<шаблон каталога>/, скопируйте всю эту папку в /bitrix/templates/.default/components/bitrix/catalog/<шаблон каталога>/ и работайте с bitrix/catalog.element/<название шаблона карточки>/template.php внутри копии.
- Шаблон сайта лежит в /local/templates/<шаблон сайта>/ (там есть header.php): скопируйте в /local/templates/<шаблон сайта>/components/bitrix/catalog.element/<название шаблона карточки>/.
- Карточка уже берётся из папки внутри /local/: ничего не копируйте, добавьте строку в template.php этой папки.

Вставьте строку в template.php копии сразу после </div>, закрывающего <div data-entity="main-button-container">. На вкладке «Кнопка» для неё есть кнопка «Скопировать»:

<?php if (\Bitrix\Main\Loader::includeModule('ziex.tryon')) { $APPLICATION->IncludeComponent('ziex:tryon.button', '', ['ELEMENT_ID' => $arResult['ID'], 'OFFER_ID' => $actualItem['ID'] ?? 0, 'CONTAINER_ID' => $itemIds['ID'] ?? ''], $component, ['HIDE_ICONS' => 'Y']); } ?>

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

Не меняйте строку:

Проверка includeModule обязательна. Без неё после удаления модуля каждый посетитель увидит красный текст 'ziex:tryon.button' is not a component.
$component четвёртым аргументом обязателен. Без него кнопка работает при первом показе и ничего не делает, когда Битрикс отдаёт карточку из кеша.

Две папки, которые нельзя создавать

Никогда не создавайте /local/templates/<шаблон сайта>/, если сам шаблон сайта лежит в /bitrix/templates/. Тогда Битрикс берёт весь шаблон сайта из этой папки, и каждая страница теряет шапку и стили. Пока такая папка есть, вкладка «Кнопка» показывает красное предупреждение и называет папку, в которой должна лежать копия.

Никогда не создавайте и /local/components/bitrix/<компонент>/. Тогда Битрикс берёт сам компонент оттуда, и на каждой карточке появляется «'bitrix:catalog.element' is not a component».

Копия больше не получает исправлений, которые Битрикс вносит в свой шаблон. Если у вашей темы собственная карточка товара, вставьте строку в неё, в то же место.

Автоматическая вставка¶

Запасной вариант, по умолчанию выключен. На вкладке «Кнопка» выберите «Автоматически, без правки шаблона» и нажмите «Сохранить». Модуль сам добавляет на страницу блок кнопки, а скрипт после загрузки страницы переносит его к основным кнопкам карточки.

Нужна карточка, устроенная как в ядре Битрикса (с блоком main-button-container), и страница каталога на компоненте ядра bitrix:catalog. В карточке другого устройства кнопка остаётся скрытой. Тогда пользуйтесь строкой в шаблоне.
Кнопка появляется после загрузки страницы, поэтому возможен небольшой сдвиг вёрстки.
Пока автоматическая вставка включена, строка в шаблоне ничего не выводит. Две кнопки на один товар не показываются никогда.

Доступ¶

На вкладке «Доступ» выберите, кто что может: «Нет доступа», «Просмотр настроек» или «Изменение настроек». Устанавливать и удалять модуль могут только администраторы.

Как проверить, что всё работает¶

На вкладке «Подключение» зелёная карточка «Подключено» с вашим аккаунтом и вашим сайтом, а «Показывать кнопку на сайте» включено.
На вкладке «Каталог и категории» в «Итоге по каталогу» число «Товаров с кнопкой примерки» больше нуля.
На вкладке «Кнопка» в списке «Строка найдена в:» есть отредактированный вами шаблон карточки, без пометок «найдена, но эта копия не используется» и «без проверки модуля».
Откройте карточку товара, раздел которого можно примерить. «Примерить» стоит под кнопками покупки. При выборе цвета примеряется фото выбранного цвета.
Нажмите кнопку, загрузите фото и дождитесь результата.
Войдите в клиентский портал на https://app.ziex-tryon.com. Примерка есть в списке задач с названием товара и ссылкой на него, а на странице API-ключей в последней метке ключа указано bitrix/0.1.4.

Обновление и удаление¶

Обновление. Распакуйте новую версию поверх /local/modules/ziex.tryon/, заменив файлы. При следующем открытии страницы настроек или при следующем запуске агента (не позже чем через час) модуль сам скопирует новые скрипт, стили и компонент кнопки и сбросит кеш кнопок для всех сайтов. Удалять модуль ради обновления не нужно: при удалении он спрашивает про данные.

Модуль сам не проверяет, вышла ли новая версия. Последняя версия каждого плагина и модуля указана в блоке integrations ответа GET /api/v1/tryon/integration. Новый архив запросите у менеджера.

Удаление. В Marketplace → Установленные решения выберите Удалить в меню строки модуля. Удаление проходит в два шага.

Страница «Удаление модуля Ziex Try-On» предупреждает, что кнопка исчезнет с карточек, а товары, разделы, заказы и шаблоны сайта не удаляются. На ней:
- Флажок «Сохранить настройки и свойство товара», по умолчанию отмечен. Если он отмечен, настройки (включая ключ) и свойство товара остаются, а при повторной установке всё вернётся. Если снят, они удаляются.
- Список шаблонов карточки, в которых есть строка с компонентом ziex:tryon.button. Строка, обёрнутая проверкой includeModule, после удаления модуля ничего не покажет. Строка без проверки помечена красным: удалите её или оберните в if (\Bitrix\Main\Loader::includeModule('ziex.tryon')) { … } до удаления.
Модуль удаляет кеш кнопок, агент, уведомления, собственные скрипт и компонент и свои обработчики событий.

Копия шаблона карточки со строкой остаётся. Пока у строки есть проверка, она безвредна.

Метка интеграции¶

Модуль называет себя сервису: bitrix/<версия>, например bitrix/0.1.4. Виджет отправляет метку с каждой примеркой, а модуль — со своими двумя серверными вызовами, в заголовке X-Ziex-Integration. Настраивать ничего не нужно. См. Идентификация.

Конфиденциальность, CSP и тестовые ключи¶

Конфиденциальность. Фото покупателя отправляется сервису. Сервис хранит фото и результат 180 дней, и политика конфиденциальности вашего магазина должна об этом говорить. Готовый абзац на русском и английском — на странице Текст для политики конфиденциальности; тот же текст с кнопками «Скопировать» есть на вкладке «Политика конфиденциальности» модуля. Согласие и передача данных за границу — вопросы к вашему юристу. Для российских магазинов это особенно важно: фото обрабатывает платформа в Соединённых Штатах.
CSP. Модуль не отправляет заголовков CSP и не выводит встроенных скриптов. Если у вашего магазина есть политика, разрешите хосты со страницы CSP. Добавьте в img-src адрес вашего CDN, если фото товаров лежат на нём.
Тестовые ключи. Поле «Ключ API» проверяет только вид ключа. Тестовые ключи нужны, чтобы собирать интеграцию; см. Тестовые ключи.

Если что-то не так¶

Пройдите список сверху вниз.

Подключено? Вкладка «Подключение» должна показывать зелёную карточку, а «Показывать кнопку на сайте» должно быть включено. Красная карточка «Не подключено» называет причину.
Раздел сопоставлен? Хотя бы один раздел товара задаёт категорию, или категория выбрана на самом товаре, и ни один раздел не помечен «Нельзя примерить». Найдите товар в «Итоге по каталогу». Товар должен быть активным и лежать в одном из «Инфоблоков каталога».
Есть фото? У товара или его торговых предложений должна быть картинка.
Строка там, откуда берётся карточка? Файл должен быть в списке «Строка найдена в:» без пометки «найдена, но эта копия не используется». В строке нужны проверка includeModule('ziex.tryon') и $component четвёртым аргументом. Пока включена автоматическая вставка, строка ничего не выводит.
Кеш. Нажмите «Сбросить кеш кнопок». Если карточка осталась прежней, очистите собственный кеш Битрикса, а при включённом композитном сайте — и композитный кеш.
Агенты. Часовая проверка — это агент Битрикса. Если агенты не выполняются (проще всего запускать их из cron), отозванный или перевыпущенный ключ замечается только по «Сохранить и проверить».
Уведомления и журнал событий. Отказ по ключу и долгий сбой вызывают уведомления в административной части, а события модуль пишет в журнал событий Битрикса.
Ключ привязан к другому сайту. Карточка называет оба домена. Попросите нас привязать ключ к нужному домену или заполните «Адрес сайта для проверки», если модуль вычислил адрес неверно.
Кнопка пишет «Сервис примерки сейчас недоступен. Попробуйте позже.» Скрипт виджета не загрузился. Проверьте свой CSP и доступность https://api.ziex-tryon.com из сети покупателя.
После первого показа кнопка ничего не делает. В строке нет $component.
Всё ещё непонятно. Включите «Отладку в консоли браузера», откройте карточку товара и посмотрите консоль браузера. Потом выключите её.

Ошибки, которые виджет показывает покупателю, перечислены на странице Ошибки. Чтобы обратиться за помощью, назовите метку bitrix/<версия> и идентификатор запроса, описанный на странице Идентификация.

Для разработчиков¶

Настройки кнопки передаются как JSON с экранированным HTML в атрибуте data-ziex-tryon-config блока <div class="ziex-tryon" data-ziex-tryon-box>. Сама кнопка — <button class="ziex-tryon-button" data-ziex-tryon>. Компонент ziex:tryon.button принимает ELEMENT_ID (обязательный), OFFER_ID, CONTAINER_ID и CACHE_TIME (по умолчанию 3600 секунд).

Кнопка кешируется вместе с карточкой каталога (catalog.element). Модуль сбрасывает этот кеш при каждом изменении настроек, при проверке ключа, при переключении расположения, при установке и удалении. Правку шаблона он не видит: после неё нажмите «Сбросить кеш кнопок».

После загрузки виджета доступен window.TryOn.on(event, fn). См. Справочник виджета.