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

Краткое руководство A — чистый HTML

Поставьте виджет примерки на страницу товара двумя тегами script. Без серверного кода и без сборки.

Что нужно

Вам понадобятся:

  • Публикуемый ключ (pk_…). Он указан на странице Integration личного кабинета клиента https://app.ziex-tryon.com. Это единственный ключ, который можно разместить на публичной странице. Никогда не кладите секретный ключ (tryon_…) в код страницы — он же открывает вход в кабинет. См. Обзор и понятия.
  • Ключ должен быть привязан к домену вашего магазина, например shop.example. Если это не так, каждый запрос с вашей страницы получит 403 KEY_NOT_BOUND; свяжитесь с нами, чтобы его привязать.

В примерах используются pk_YOUR_PUBLISHABLE_KEY и магазин shop.example. Чтобы попробовать страницу без затрат, возьмите ключ pk_test_… — см. Локальная разработка.

1. Добавьте виджет

<script src="https://api.ziex-tryon.com/embed/tryon-embed.js"></script>
<script>
  TryOn.init({
    apiKey: 'pk_YOUR_PUBLISHABLE_KEY',
    productImage: 'https://shop.example/images/linen-shirt.jpg',
    productTitle: 'Льняная рубашка',
    productUrl: 'https://shop.example/p/linen-shirt',
    category: 'tops',
    lang: 'ru'
  });
</script>

На странице появится плавающая кнопка «Примерить». Покупатель нажимает её, выбирает фото, и виджет отправляет фото и одежду в API, следит за задачей и показывает результат.

Загружайте tryon-embed.js с https://api.ziex-tryon.com/embed/. Виджет берёт адрес API оттуда, откуда загружен его скрипт, поэтому копия файла на вашем сервере отправляла бы запросы на ваш сервер.

Опция Значение
apiKey Обязательна. Публикуемый ключ pk_….
productImage URL фото одежды. URL на другом хосте допустим.
productTitle Название товара; хранится вместе с задачей, чтобы вы видели, для чего была примерка.
productUrl Страница товара. Сохраняется, только если это обычный http(s) URL; с публикуемым ключом он должен быть на вашем привязанном домене.
category tops, outerwear, bottoms, one-pieces или auto. Актуальный список — GET /api/v1/tryon/capabilities (ключ не нужен).
lang ru или en. По умолчанию виджет читает <html lang>.
launcher false скрывает плавающую кнопку; виджет открывает ваша страница (ниже).

Если вы не передадите productImage или productTitle, виджет попробует найти их на странице (структурированные данные, теги Open Graph, первый h1). Надёжнее передавать их самим. Все опции, события и update() — в Справочнике виджета.

2. Используйте свою кнопку

С launcher: false виджет не рисует кнопку и не выполняет проверку домена при загрузке; ваша страница вызывает TryOn.open():

<button id="tryon-button" type="button">Примерить</button>

<script src="https://api.ziex-tryon.com/embed/tryon-embed.js"></script>
<script>
  TryOn.init({
    apiKey: 'pk_YOUR_PUBLISHABLE_KEY',
    productImage: 'https://shop.example/images/linen-shirt.jpg',
    productTitle: 'Льняная рубашка',
    productUrl: 'https://shop.example/p/linen-shirt',
    category: 'tops',
    launcher: false
  });
  document.getElementById('tryon-button').addEventListener('click', function () {
    TryOn.open();
  });
</script>

Когда товар меняется без перезагрузки страницы (выбор цвета или размера), вызывайте TryOn.update({ productImage: '…' }), а не destroy() и повторный init() — см. Справочник виджета.

3. Привяжите ключ к домену

Публикуемый ключ работает только на домене, к которому привязан: сам домен, www. и любой поддомен. Запрос с другого сайта — 403 DOMAIN_NOT_ALLOWED, а запрос без Origin и Referer — 403 ORIGIN_REQUIRED: публикуемый ключ работает со страницы в браузере, а не с сервера.

Ключ можно проверить из командной строки, отправив тот Origin, который отправил бы браузер:

curl -i https://api.ziex-tryon.com/api/v1/tryon/domain-check \
  -H 'X-API-Key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Origin: https://shop.example'

{
  "allowed": true,
  "domain": "shop.example",
  "client_name": null,
  "plan_id": null,
  "limit_exceeded": false,
  "limit_remaining": null,
  "mode": "live"
}

200 означает, что ключ можно использовать с этого хоста. Публикуемый ключ получает из сведений об аккаунте только limit_exceeded (и mode); client_name, plan_id и limit_remaining остаются null — они для секретного ключа. Отказ — это 403 с error.code DOMAIN_NOT_ALLOWED, KEY_NOT_BOUND или ORIGIN_REQUIRED; ориентируйтесь на код, а не на сообщение. Виджет выполняет ту же проверку при запуске (кроме launcher: false) и скрывает свою кнопку только если limit_exceeded равен true.

4. Загружайте виджет лениво

Виджет — довольно объёмный скрипт. Чтобы загружать его только при первом нажатии на вашу кнопку, используйте небольшой загрузчик https://api.ziex-tryon.com/embed/tryon-loader.js. Он определяет глобальный объект ZiexTryOn с двумя функциями:

  • ZiexTryOn.hasPending(pk) возвращает true, когда эта вкладка браузера хранит примерку, отправленную с одной из предыдущих страниц вашего магазина и ещё не показанную.
  • ZiexTryOn.load([scriptUrl]) один раз загружает скрипт виджета и возвращает Promise, который выполняется значением TryOn. scriptUrl необязателен.

Отправленная примерка оплачена и продолжается, когда покупатель переходит на другую страницу. Поэтому загрузчик должен быть на каждой странице, а страница, где hasPending равен true, обязана сразу загрузить виджет, не дожидаясь клика, — иначе покупатель так и не увидит результат:

<button id="tryon-button" type="button">Примерить</button>

<script src="https://api.ziex-tryon.com/embed/tryon-loader.js"></script>
<script>
  var PK = 'pk_YOUR_PUBLISHABLE_KEY';
  var config = {
    apiKey: PK,
    productImage: 'https://shop.example/images/linen-shirt.jpg',
    productTitle: 'Льняная рубашка',
    productUrl: 'https://shop.example/p/linen-shirt',
    category: 'tops',
    launcher: false
  };

  var ready = null;
  function widget() {
    if (!ready) {
      ready = ZiexTryOn.load().then(function (t) { t.init(config); return t; });
    }
    return ready;
  }

  if (ZiexTryOn.hasPending(PK)) {
    widget();                                   // подхватывает прежнюю примерку
  }
  document.getElementById('tryon-button').addEventListener('click', function () {
    widget().then(function (t) { t.open(); });  // первый клик загружает, следующие только открывают
  });
</script>

Пока итог ждёт покупателя, виджет ставит на элемент <html> атрибут data-tryon-ready="result" (или "error"), поэтому ваша кнопка может показать точку CSS-правилом на html[data-tryon-ready]. Подробности подхвата — на странице Ленивая загрузка и подхват.

5. Разрешите виджет под Content Security Policy

Если ваш сайт отправляет Content-Security-Policy, разрешите https://api.ziex-tryon.com для скриптов и соединений и https://media.ziex-tryon.com для изображений. Точные директивы — на странице о CSP.

Дальше