Перейти к содержанию

Создание плагина

Чек-лист для тех, кто пишет плагин или модуль для CMS или платформы магазинов, который подключает магазин к Ziex Try-On. Проходите пункты по порядку. Плагин, прошедший все пункты, ведёт себя так же, как плагин WooCommerce и модуль 1С-Битрикс. Эти же проверки подходят как приёмочный тест вашего плагина.

Это не автоматический тест

Это чек-лист, который вы выполняете вручную. Скрипта, который проходит его за вас, мы пока не публикуем.

Устройство плагина

У плагина две половины:

  • Серверная работает на сервере магазина. Она хранит секретный ключ (tryon_…) и обращается к API.
  • Страничная выводится на страницу товара. Она знает только публикуемый ключ (pk_…) и запускает виджет.

Секретный ключ не покидает сервер. Если он попал на страницу, его прочитает любой посетитель, а он ещё и открывает вход в личный кабинет клиента с фотографиями покупателей. См. Ключи.

1. Подключите сайт

  1. [ ] Спросите API о сайте. С сервера вызовите GET /api/v1/tryon/integration?site_url=<адрес магазина>, передав секретный ключ в X-API-Key. Вызывайте его, когда владелец магазина сохраняет ключ и когда открывается страница настроек, а не при каждом просмотре страницы: он входит в общий лимит запросов (см. Лимиты), а ответ меняется редко.
  2. [ ] Прочитайте site.allowed. Выводите виджет, только когда значение true. Если false, причину называет site.reason: key_not_bound (у ключа нет привязанного домена), domain_mismatch (ключ принадлежит другому сайту) или dev_host (боевой ключ на тестовом хосте). Покажите владельцу магазина подходящее сообщение; для dev_host напишите «используйте тестовый ключ на локальном сайте». Соответствие причин кодам ошибок — в Ошибках.

  3. [ ] Используйте остальной ответ. Поля, которые нужны плагину:

    Поле Что это
    site.allowed, site.reason, site.host Может ли этот сайт использовать ключ, почему нет, и хост сайта в том виде, как его читает API.
    key.publishable_key Ключ pk_…, который выводится на страницу.
    key.mode live или test. Для test скажите владельцу магазина, что деньги не списываются, а результат имитируется.
    key.domain, client.name Привязанный домен и название аккаунта — для страницы настроек.
    plan Название тарифа, его лимит, использовано и осталось генераций, дата сброса.
    widget.script_url, widget.api_url Скрипт виджета и адрес API с нашего хоста.
    capabilities Категории, которые поддерживает сервис (ниже).
    integrations Для каждого известного плагина или модуля: latest_version, download_url (или null, если архив мы передаём сами) и docs_url. С его помощью сообщите владельцу, что вышла новая версия вашего плагина.

  4. [ ] Называйте плагин в каждом серверном вызове. Отправляйте X-Ziex-Integration: <name>/<version> и собственный User-Agent (см. Идентификация и Краткое руководство B).

2. Безопасно выведите виджет

  1. [ ] Ни одного ключа tryon_… на странице. Проверьте страницу, которую выдаёт плагин: HTML, встроенный скрипт, файлы JavaScript, cookie и данные, которые передаются во фронтенд. Строка, начинающаяся с tryon_, не должна встречаться нигде. Допустим только pk_….
  2. [ ] Адрес скрипта и ключ берите только из нашего ответа. Используйте widget.script_url и widget.api_url из ответа integration, а также key.publishable_key. Не берите их из настройки, которую владелец магазина может ввести сам, и не собирайте самостоятельно. Скрипт всегда загружается с https://api.ziex-tryon.com/embed/; не копируйте tryon-embed.js на сервер магазина, потому что виджет берёт адрес API оттуда, откуда загружен его скрипт.

  3. [ ] Инициализируйте виджет с такими опциями (все описаны в Справочнике по виджету):

    Опция Значение
    apiKey Публикуемый ключ, pk_….
    productImage Главное изображение товара, URL с https://.
    productTitle Название товара.
    productUrl Адрес страницы товара.
    category id категории из GET /api/v1/tryon/capabilities (или из блока capabilities ответа integration): tops, outerwear, bottoms, one-pieces либо auto, если товар не удаётся сопоставить (если только auto.available не равно false). Не зашивайте список в код: он растёт.
    launcher false. Плагин рисует свою кнопку и вызывает TryOn.open().
    lockCategory true. Категорию выбрал магазин, покупателя о ней не спрашивают.
    integration "<name>/<version>", например "acme-cms/1.0.0".

  4. [ ] Подхватывайте примерку после смены страницы. Загружайте виджет лениво, но сразу — на странице, где вкладка хранит идущую примерку, иначе покупатель не увидит результат. Используйте ZiexTryOn.hasPending(pk) и ZiexTryOn.load() загрузчика; не копируйте правило слота. См. Отложенную загрузку и подхват.

  5. [ ] Разрешите виджет в Content-Security-Policy страницы, если магазин её задаёт. См. CSP. Плагину, который добавляет встроенный скрипт, нужен собственный механизм nonce платформы.

3. Проверьте тестовым ключом

Делайте это на стенде разработки с тестовым ключом, он ничего не стоит. См. Тестовые ключи и Локальную разработку.

  1. [ ] Проверьте тестовый ключ. GET /api/v1/tryon/integration с тестовым секретным ключом отвечает key.mode: "test". На локальном или промежуточном хосте site.allowed равно true, если хост разрешён для ключа.
  2. [ ] Отправьте с сервера одну примерку с Idempotency-Key, затем опрашивайте GET /api/v1/tryon/status/{job_id} до completed. Фото должно быть загрузкой (data URI). Повтор того же запроса с тем же ключом должен ответить 200 с той же задачей и не создавать вторую. См. Краткое руководство B.
  3. [ ] Один раз запустите виджет на странице стенда с pk_test_… тестового ключа: откройте окно, отправьте фото, дойдите до результата. В окне виден значок «TEST».
  4. [ ] Проверьте подпись вебхука на перехваченной доставке. Зарегистрируйте эндпоинт в режиме test, отправьте тестовую примерку и проверьте X-TryOn-Signature-V2 по сырым байтам тела, с отказом при устаревшей метке времени. См. Вебхуки.

4. Расскажите покупателю

  1. [ ] Дайте магазину абзац для политики конфиденциальности. Фото покупателя передаётся сервису, и магазин обязан об этом сказать. Покажите владельцу готовый текст со страницы Текст для политики конфиденциальности и скажите добавить его в политику.
  2. [ ] Обрабатывайте ошибки по коду, а не по тексту. Для каждого кода покажите покупателю понятное сообщение, а исходный текст оставьте для своего журнала. См. Ошибки.

Примеры для изучения

Два плагина — готовые примеры этого чек-листа:

  • Плагин WooCommerce. Архив: https://app.ziex-tryon.com/downloads/ziex-tryon-woocommerce.zip.
  • Модуль 1С-Битрикс. Архив мы передаём напрямую; напишите нам.

Когда плагин готов, напишите нам (см. Контакты): название и метку версии, которую он отправляет.