Интеграция

Установка и настройка виджета Чекаута Shiptor

Версия 1 от 06.10.2020 — История изменений

Система обработки заказов Чекаут Shiptor отличается простотой интеграции с любой CMS клиента. Это связано с тем, что для работы с ней достаточно иметь доступ к файлам с расширениями .html и .js. Более подробная информация о возможностях и функциях Чекаута Shiptor есть в нашем блоге

Посмотреть пример работы заказного виджета можно в демо-версии.

Установка Чекаута

Для установки виджета необходимо подключить файл, который находится по адресу: https://checkout.shiptor.ru/embed/order.js.

Не копируйте и не сохраняйте файл! Это может привести к нарушению работоспособности виджета в дальнейшем.

Сделать это можно в теге body желаемой страницы следующим образом:

<script type="text/javascript" src="https://checkout.shiptor.ru/embed/order.js"></script>

Так же необходимо создать контейнер виджета и указать в нем виджет-ключ для авторизации с сервисом Чекаута Shiptor

Корзина виджета выглядит следующим образом:

После нажатия на кнопку «Оформить заказ» покупатель попадает в форму оформления заказа.

Здесь он заполняет необходимые поля, выбирает желаемый способ оплаты и нажимает кнопку «Оформить заказ». Заказ будет создан в кабинете Чекаута Shiptor. Если была выбрана оплата онлайн, то система сразу перенаправляет на страницу оплаты заказа. Оплата осуществляется через платежный сервис, выбранный в кабинете Чекаута Shiptor. При работе с некоторыми из них доступно автоматическое получение данных об успешно оплаченных заказах с установкой им статуса «Оплачен». Для всех остальных требуется ручная проверка и подтверждение.

Задание контейнера виджета явным образом

Виджет опирается на HTML-контейнер вида

<div id="shiptor_widget" class="_shiptor_widget"></div>

Через него можно передать все стартовые параметры, которые, в свою очередь, могут быть:

Параметр Описание Пример
data-wk Виджет-ключ, который предназначен для авторизации всех запросов виджета. Получить его можно в кабинете Чекаута, в разделе Настройки > Общие. data-wk="XXXXXXXXXXXXXXX"
data-weight Вес для расчета доставки, если данный параметр у товаров не заполнен. В зависимости от настроек в кабинете Чекаута может быть использован как вес для всей посылки или как вес для одного товара. Задается в килограммах. Вес можно указать в настройках кабинета Чекаута. data-weight="2"
data-dimensions Габариты для расчета доставки, если у товаров не заполнены соответствующие поля. В зависимости от настроек в кабинете Чекаута могут быть использованы габариты всей посылки или отдельного товара. Значения задаются в сантиметрах. Для этого используются JSON-запросы, где length - длина, width - ширина и height - высота. Габариты можно указать в кабинете Чекаута. data-dimensions='{"length":25, "width":10, "height":20}'
data-cod Признак наложенного платежа. Определяет алгоритм выполнения первичного расчета доставки: с наложенным платежом или без него. Задается числом, где 1 - наложенный платеж, 0 - наложенный платёж отсутствует. Значение по умолчанию - 1. data-cod="1"
data-kladr КЛАДР-код населенного пункта по умолчанию. Задается 11-значным числом. По умолчанию будет взят КЛАДР код Москвы. data-kladr="77000000000"
data-city Отображение названия населённого пункта в строке местоположения. Параметр обязателен к вводу, если указан data-kladr. data-city="Москва"
data-basketShowOnAdd

Настройка работы корзины. Параметр позволяет управлять ее всплыванием при добавлении туда очередного товара. Задается числом, где 1 - да, 0 - нет. При -1 сразу открывается форма оформления заказа. Значение по умолчанию - 1.

data-basketShowOnAdd="0"
data-country Страна по умолчанию. Возможны варианты: Беларусь, Россия или Казахстан. Все остальные страны задаются двухбуквенным символьным кодом. data-country="Беларусь"
data-linkYmaps Подключение Яндекс.Карт в виджете. Если на странице с ним сервис уже используются, отключите его, чтобы избежать ошибок с отображением карты. Значение параметра задаётся цифрами: 1, если сервис нужно подключить, и 0, если нет. Значение по умолчанию - 1. data-linkYmaps= "0"
data-yk Позволяет указать API-ключ Яндекс.Карт для подключения поисковой строки по карте.  Получить его можно в «Кабинете разработчика»: нажмите «Получить ключ», выберите JavaScript API и HTTP Геокодер. data-yk = "XXXXX"
data-basketPos

Положение иконки корзины. Доступно два возможных варианта: right (справа квадратом с пиктограммой корзины) и bottom (полосой в нижней части окна браузера). Значение по умолчанию - right.

data-basketPos="bottom"

data-payment-redirect-delay

Автоматическая переадресация для заказов с онлайн-оплатой. Определяется путём задания временного интервала между успешным оформление заказа и переадресацией на страницу оплаты.

data-payment-redirect-delay="4000"

Чтобы виджет имел возможность работать с товарами конкретного сайта, их надо предварительно выгрузить в номенклатуру личного кабинета Shiptor. В этом случае для создания кнопки добавления в корзину достаточно будет воспользоваться любым html-узлом, корректно обрабатывающим событие click.

Лучше всего для этого подходит тег a. Чтобы сделать такую кнопку для товара, нужно создать следующий html-код:

<a href="#" data-role="shiptor_widget_add_basket" 
data-id="артикул товара (варианта 1)" data-q="1" 
data-product="артикул товара">Добавить в корзину 1шт товара</a>

Здесь критичны следующие параметры:

  • data-role="shiptor_widget_add_basket" - добавление товара в корзину;
  • data-id="артикул товара из ЛК Shiptor"- передача идентификатора товара. Важно указать значение «Артикул магазина » (shopArticle) из номенклатуры товара в ЛК Shiptor.
  • data-q="1" - определение количества единиц товара, которые добавляются в корзину за один клик.
  • data-product="артикул товара" - синхронизация количества и выбранной вариации товара. Параметр необходим в том случае, если у вас реализованы вариативные товары и/или выбор количества товара, добавляемого в корзину.

При каждом нажатии на кнопку товар добавляется в корзину с предварительным запросом на получение информации из ЛК Shiptor. В качестве стоимости используется поле «Розничная цена» (retailPrice).

Если реализовано поле, позволяющее выбрать количество товаров, виджет может отслеживать изменения в автоматическом режиме. Чтобы он синхронизировал их с кнопкой добавления в корзину, необходимо в поле количества добавить 2 следующих параметра

<input type="text" name="quantity" value="1" data-role="shiptor_widget_change_quantity" 
data-target="артикул товара(родителя)"/>
  • data-role="shiptor_widget_change_quantity" - так виджет поймет, что это поле отвечает за количество товара, добавляемого в корзину.
  • data-target="артикул товара" - синхронизация количества будет выполняться для кнопки добавления в корзину с параметром data-product, равным значению этого атрибута. Это сделано специально, чтобы на одной странице можно было без проблем выбрать любые интересующие товары.

Если у товара есть несколько вариаций, то используйте параметр, который отслеживает артикул в каждом конкретном случае.

<select name="variation" data-role="shiptor_widget_variant_change" 
data-target="артикул родителя">
<option value="артикул варианта 1">Носки зеленые</option>
<option value="артикул варианта 2">Носки красные</option>
<option value="артикул варианта 3">Носки синие</option>
</select>
  • data-role="shiptor_widget_variant_change" - выбор вариации, добавляемой в корзину.
  • data-target="артикул родителя" - синхронизация количества будет выполняться для кнопки добавления в корзину с параметром data-product, равным значению этого атрибута. Это сделано специально, чтобы на одной странице можно было разместить множество кнопок добавления в корзину для разных товаров.

В обоих случаях синхронизация выполняется путём отслеживания события change на соответствующих полях.

События

Чтобы транслировать действия пользователей, виджет использует механизм браузерных событий. Для получения необходимой информации установите их обработчик. События срабатывают только на контейнере виджета. В обработчик передаётся один аргумент, у которого в поле detail содержатся передаваемые данные. Список поддерживаемых событий следующий:

Название события Описание Доступные в detail данные
onBasketAdd Вызывается на добавление новой товарной позиции в корзину. Информация о товаре.
onBasketUpdate Вызывается на изменение количества товара в корзине. Информация о товаре.
onBasketRemove Вызывается на удаление товарной позиции из корзины. Информация о товаре.
onBasketClean Вызывается, когда покупатель пользуется кнопкой «Очистить корзину». пустой объект
onWidgetInit Вызывается, когда подключены все необходимые обработчики на странице. Срабатывает однократно на загрузке виджета. пустой объект
onWidgetBasketShow Вызывается, когда завершается отрисовка корзины виджета. Срабатывает на каждой отрисовке корзины виджета. пустой объект
onWidgetOrderShow Вызывается, когда завершается отрисовка оформления заказа виджета. Срабатывает на каждый вызов процедуры. пустой объект
onOrderSend Вызывается, когда создается новый заказ. Информация о заказе

Создать обработчик можно следующим образом

var shiptorWidget = document.querySelector('#shiptor_widget');
shiptorWidget.addEventListener('onBasketAdd',function(customEvent){
    console.log(customEvent.detail);
});

Подключение своих стилей к виджету

Чтобы использовать свои стили, подключите файл .css после инициализации виджета. Как это сделать показано на примере.

var shiptorWidget = document.querySelector('#shiptor_widget');
shiptorWidget.addEventListener('onWidgetInit',function(){

    var fileref = document.createElement("link");
    fileref.setAttribute("rel", "stylesheet");
    fileref.setAttribute("type", "text/css");
    fileref.setAttribute("href", '/pat/to/your/custom/style.css');  //Путь к вашему css файлу
    if(typeof fileref !== "undefined"){
        document.getElementsByTagName("head")[0].appendChild(fileref)
    }
});

Результат работы такого кода выглядит следующим образом:

Примеры интеграции виджета Чекаута с популярными CMS подробно описаны в инструкции. Для доступа к интересующей системе выберите соответствующий пункт в правом навигационном меню.

История изменений