Designed with by Xiaoying Riley

Виджет

Виджет предназначен для предоставления информации о стоимости и условиях доставки на любой странице вашего сайта.
Может быть встроен практически на любой сайт, исключая полностью закрытые для редактирования кода.

Основные возможности:

  • Предоставление информации о стоимости и сроках доставки
  • Предоставление информации об адресах пунктов выдачи заказов
  • Реализация корзины даже на полностью статичном сайте
  • Оформление и отправка заказа на электронную почту или на указанный вами скрипт.

Виджет в карточке товара заметно повышает информативность сайта для посетителей и как следствие конверсию сайта. Так же виджет часто вешают на страницу О доставке.

Демонстрационная страница: https://eshoplogistic.ru/widget.

Настройка в личном кабинете

Настройка виджета производится во всплывающем окне на странице настройки сайтов: https://eshoplogistic.ru/domains.
Для открытия окна настройки виджета необходимо кликнуть по ссылке «включить и настроить» или «настроить», если виджет уже был включён ранее.

§ Настройки виджета
Включён Включить / выключить виджет
Запрашивать сразу все службы При включении виджет будет запрашивать сразу все доступные службы формируя список.
 пример   демонстрация.
Пытаться определить город посетителя При запуске виджет пытается определить город посетителя и сразу произвести запрос доставок, т.е. посетителю не нужно указывать город для доставки.

Внимание

- Требует передачи IP-адреса посетителя при инициализации виджета, подробнее в разделе «Параметры».
- Точное определение города по IP-адресу не всегда возможно (точность 60-80%).
Скрыть логотип eShopLogistic Убрать из окна ыиджета логотип eShopLogistic и ссылку для регистрации в сервисе.

Внимание

Работает только на платных тарифах с положительным балансом
Разрешить отправку заказа Появляется возможность отправки заказа из виджета.  пример
Отправка заказа Доступно 2 варианта:
  • «на почту» - заказ будет отправлен на адрес, указанный в поле «E-mail для отправки заказа».
  • «на ваш скрипт» - заказ будет отправлен на URL, указанный в поле «Скрипт обработки заказа».
E-mail для отправки заказа Для варианта отправки заказа «на почту».
Скрипт обработки заказа Для варианта отправки заказа «на ваш скрипт».
Необходимо указать URL вашего скрипта; на него сервис отправит POST-массив с данными заказа. Эта функция удобна, если вы хотите, чтобы заказы из виджета проходили не просто на почту, а были обработаны вашей системой (CMS, CRM).
Форма заказа Настройка полей оформления заказа: название, включение, обязательность.
Настройка названий некоторых элементов виджета.
Режим корзины Включает режим корзины: на любом даже статичном сайте можно добавлять товары в корзину, затем получить информацию по доставкам и отправить заказ.
 пример   демонстрация.
Как показывать количество товаров в корзине? Доступно 2 варианта: «количество отдельных товаров» и «общее количество всех товаров».
Показывать сумму корзины? Иконка корзины дополняется информацией по сумме стоимости товаров в корзине.
Настройка расположения и цвета иконки корзины на вашем сайте.  пример
Содержит ключ и секретный код для подключения виджета на вашем сайте.
Подробнее ниже, в разделе «Подключение на сайте».

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

§ Простой виджет расчтёта стоимости и срока доставки
    
    <div id="eShopLogisticWidgetForm" data-key="[KEY]"></div>
    <script src="https://api.eshoplogistic.ru/widget/form/app.js"></script>
    

Поддерживаются параметры:

  • data-weight - вес груза по умолчанию
  • data-dimensions - габариты груза по умолчанию
  • data-ip - IP-адрес посетителя сайта для автоопределения города доставки (как правило подставляется средствами CMS)
  • data-from - город-отправитель по умолчанию
Пример:
    
    <div id="eShopLogisticApp" data-weight="5" data-dimensions="25*25*15" data-key="[KEY]"></div>
    
§ Виджет во всплывающем окне

Виджет открывается по нажатию ссылки/кнопки, которые оформляются и настраиваются на вашем сайте.

Ключевым элементом управляющего html-элемента является атрибут data-widget-button.

Для подключения виджета, на всех нужных страницах вашего сайта внизу, перед тегом </body>, добавьте следующий код:

    
    <button type="button"
            data-widget-button
            data-article="158"
            data-name="Кроссовки New Balance"
            data-price="6400"
            data-unit="пара"
            data-image="https://site.ru/img/product1.png"
            data-weight="2,5">
        Рассчитать доставку
    </button>
    <div id="eShopLogisticApp" data-key="[KEY]"></div>
    <script src="https://api.eshoplogistic.ru/widget/modal/v1/app.js"></script>
    

Где: [KEY] — ключ виджета для данного сайта. Доступен на вкладке «Подключение» в окне настройки виджета.

§ Виджет, встраиваемый в страницу

Виджет открывается по нажатию ссылки/кнопки, которые оформляются и настраиваются на вашем сайте.

Ключевым элементом управляющего html-элемента является атрибут data-widget-load.

Для подключения виджета:

1. на всех нужных страницах вашего сайта внизу, перед тегом </body>, добавьте следующий код:

    
    <script src="https://api.eshoplogistic.ru/widget/static/v1/app.js"></script>
    

2. в нужном месте страницы разметите управляющий html-элемент (кнопка/ссылка/вкладка ...) и блок виджета

    
    <button type="button" data-widget-load>Заказать с доставкой</button>
        <div id="eShopLogisticStatic"
     data-key="[KEY]"
     data-autoload="1"
     data-all-services="1"
     data-article="00000125"
     data-name="ВЕЛОСИПЕД ГОРНЫЙ ST30 ROCKRIDER"
     data-price="12800"
     data-image="/assets/images/product.webp"
     data-weight="12">
	</div>
    

Где: [KEY] — ключ виджета для данного сайта. Доступен на вкладке «Подключение» в окне настройки виджета.

Пример инициализации виджета на событие скролла страницы:

    
        <script>
            window.addEventListener('scroll', event => {
                const root = document.getElementById('eShopLogisticStatic');
                if(document.documentElement.scrollTop > 300) {
                    root.dispatchEvent(new CustomEvent('eShopLogistic:load'));
                }
            })
        </script>
    

§ Настройка кнопки запуска виджета / добавления в корзину
    
    <!-- для одного товара -->
    <button type="button" data-widget-button 
        data-article="158" 
        data-name="Кроссовки New Balance" 
        data-price="6400" 
        data-unit="пара"
        data-image="/assets/images/product.webp"
        data-weight="2.5">
        В корзину
    </button>

    <!-- для набора товаров (например составной товар или содержимое корзины) -->
    <button type="button" data-widget-button 
        data-offers="[{"article":"1","name":"Подушка","count":1,"price":150,"weight":0.3},{"article":"2","name":"Маска","count":1,"price":50,"weight":0.2},{"article":"3","name":"Беруши","count":1,"price":30,"weight":0.1}]">
        В корзину
    </button>
    
Здесь использованы data-атрибуты:
data-атрибут Описание
weight
обязательный
Вес в кг
article Идентификатор товара в вашей системе. Необходим, если заказ будет отправляться на внешний крипт.
name , unit Название и единица измерения товара. Необходимо указывать для отображения в виджете.
image URL изображения товара. Например: https://ваш_сайт.ru/product.jpg
price Стоимость товара. Необходимо указывать, если виджет работает в режиме корзины, а также для верного расчёта стоимости доставки с учётом страховки или применения правил коррекции.
offers JSON-строка с данными набора товаров.
По клику на кнопке, вместо 1 товара вы можете добавить в виджет сразу несколько. Например, содержимое корзины посетителя (если у вас уже используется штатная корзина) или набор связанных товаров.
options JSON-строка с опциями товара.
В разработке. Принцип работы данного параметра может быть изменен в будущем.

Например:
[{"article":"001","value":"чёрный","name":"Цвет","active":true},{"article":"001","value":"XL","name":"Размер","active":true}]

Параметры

Помимо основных параметров запуска виджета, указанных в разделе «Подключение на сайте», существуют дополнительные data-атрибуты.
Эти атрибуды предназначены для переопределения настроек виджета для данной страницы/кнопки без изменения настроек в Личном кабинете.

Все атрибуты делятся на 2 группы:
  • Глобальные (для <div id="eShopLogisticApp"></div>).
    Определяют параметры запуска виджета на данной странице.
  • Локальные (для конкретной кнопки запуска виджета).
    Определяют параметры запуска виджета для данной кнопки.
Используется, например, для страниц типа «Доставка», где нужно указать примерную стоимость доставки без конкретных товаров.
Атрибут Описание
data-from
глобальный

Изменение города-отправителя.
В качестве значения используется ФИАС-код населённого пункта.

Пример (изменит город-отправитель на Тверь):
<div id="eShopLogisticApp" data-from="c52ea942-555e-45c6-9751-58897717b02f"></div>

ФИАС-код можно узнать на сайте Федеральной Адресной Системы: https://fias.nalog.ru/ExtendedSearch.

data-basket-mode
глобальный
Включение/выключение режима корзины.
Пример: <div id="eShopLogisticApp" data-basket-mode="0"></div>
data-all-services
глобальный
Включение/выключение режима «Запрашивать сразу все службы».
data-offers-hide
глобальный
Включение/выключение списка товаров в окне виджета. По умолчанию - 0.
data-modal-title
глобальный
Изменяет заголовок окна виджета на указанный.
data-allow-send
глобальный
Включение/выключение возможности отправки заказа.
data-no-form
глобальный

Если этот параметр существует и равен 1, то форма ввода данных клиента и итоговое сообщение не показываются. Срабатывает функция обратного вызова onClickButtonOrder и виджет просто закрывается.

Может пригодиться для встраивания виджета в корзину на вашем сайте.

data-payments-hidden
глобальный
Если этот параметр существует и равен 1, то в виджете не будут показаны способы оплаты.
data-ip
глобальный
IP-адрес посетителя для автоматического определения города.
data-dimensions
локальный
Для более точного расчёта стоимости доставки можно указать габариты в формате Д*Ш*В в сантиметрах.
Например:
<button type="button" data-widget-button data-dimensions="25*15*10" data-article="158" data-name="Кроссовки New Balance" data-price="6400" data-unit="пара" data-weight="2.5"> В корзину </button>
data-count
локальный
Количество. По умолчанию количество единиц товара равно 1. Вы можете указать иное с помощью данного параметра.
data-currency
локальный
Валюта. По умолчанию «р.», Вы можете указать иное с помощью данного параметра.

Отправка заказов в CMS/CRM

В зависимости от значения параметра «Отправка заказа», заказ из виджета может быть отправлен на указанный вами адрес электронной почты или на указанный URL.
В последнем случае, сервис отправит на указанный URL массив данных заказа, которые вы можете принять и обработать, как вам удобно:

    
    // пример входящего массива $_POST
    [weight] => 2.5
    [idShipper] => {"name":"СДЭК","from":"44","keyShipper":"sdek"}
    [selectedDelivery] => {"price":396,"time":"1-2 дня","base_price":252,"comment":null,"key":"terminal","name":"Самовывоз из пункта выдачи"}
    [selectedPayment] => {"key":"cashless","name":"Безналичный расчёт","comment":null}
    [costDelivery] => 396
    [totalCost] => 14834
    [city] => {"fias":"c52ea942-555e-45c6-9751-58897717b02f","name":"Тверь","postal_code":"170000","region":"Тверская область","sub_region":"","type":"город"}
    [offers] => [{"article":"2093","name":"Весы порционные CAS PW-2H","price":14438,"summ":14438,"unit":"шт.","count":1,"weight":2.5}]
    [addressForDelivery] => пр-т. Октябрьский, 99 // адрес доставки
    [name] => Алексей
    [email] => mail@mail.ru
    [phone] => 891000100203
    [query_mode] => widget
    [secret] => f6994dc130abs4df93e39536545e663e57
    [comment] => комментарий к заказу
    

Где:
secret — секретный код виджета, указанный на вкладке «Подключение» окна настройки виджета.
Вы можете фильтровать данные, приходящие на ваш скрипт, используя этот код. Например, на один скрипт можно принимать заказы с нескольких сайтов.

price — итоговая стоимость доставки.
base_price это исходная цена доставки, полученная от транспортной компании. Если данный параметр присутствует в ответе, значит к цене транспортной компании было применено корректирующее правило.

В ответ ожидается строка JSON в формате:

    
    {
        "success":true, // true / false - статус завершения операции создания заказа
        "message":"Заказ отправлен!" // текстовое сообщение для виджета (может быть пустым)
    }
    

Функции обратного вызова

В процессе работы виджета предусмотрены функции обратного вызова, которые вы можете использовать.

Внимание

Функции обратного виджета не поддерживаются в информационном виджете: https://eshoplogistic.ru/widget-form.

    
document.addEventListener('eShopLogistic:ready', () => {

    eShopLogistic.onInitCart = function (response) {
        console.log('Инициализация корзины', response)
    }

    eShopLogistic.onAddToCart = function (response){
        console.log('Добавление в корзину:', response)
    }
    
    eShopLogistic.onChangeCountOffer = function (response){
        console.log('Изменение количества в корзине:', response)
    }
    
    eShopLogistic.onChangeOptionOffer = function (response){
        console.log('Изменение опции в корзине:', response)
    }
    
    eShopLogistic.onDestroyData = function (){
        console.log('Очистка введенных данных виджета')
    }
    
    eShopLogistic.onRemovePositionFromOffers = function (response){
        console.log('Удаление предложения в корзине:', response)
    }
    
    eShopLogistic.onSelectedCity = function (response) {
        console.log('Выбор города:', response)
    }
    
    eShopLogistic.onSelectedPayment = function (response){
        console.log('Выбор варианта оплаты:', response)
    }
    
    eShopLogistic.onSelectedService = function (response){
        console.log('Выбор службы доставки:', response)
    }
    
    eShopLogistic.onSelectedTypeDelivery = function (response){
        console.log('Выбор типа доставки:', response)
    }
    
    eShopLogistic.onClickButtonOrder = function (response){
        console.log('Клик по кнопке «Заказать»', response)
    }
        
    eShopLogistic.onSubmitForm = function (response){
        console.log('Отправка заказа:', response)
    }

    eShopLogistic.onSelectedPVZ = function (response){
        console.log('Выбор ПВЗ:', response)
    }
})      
    

Доступные функции:

callback Описание
onAddToCart Добавление в корзину
onChangeCountOffer Изменение опции в корзине
onDestroyData Очистка введенных данных виджета
onRemovePositionFromOffers Удаление товара в корзине
onSelectedCity Выбор города
onSelectedPayment Выбор варианта оплаты
onSelectedService Выбор службы доставки
onSelectedTypeDelivery Выбор типа доставки
onSubmitForm Отправка заказа

Специальный виджет для корзины сайта

Данны виджет предназначен специально для встраивания на страницу оформления заказа. На его основе создаются модули для CMS.

Внимание

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

Приведённые фрагменты js-кода предназначены для иллюстирования и не будут работать «как есть».

 

Описание

Для работы виджет требует предварительного выбора города, перечень товаров текущей корзины пользователя, выбранный метод оплаты.

При загрузке страницы происходит инициализация виджета и его запуск. Если все необходимые параметры указаны верно, виджет показывает все доступные варианты доставки.

Виждет имеет несколько методов, а также генерирует события в ответ на действия пользователя. Соответственно, взаимосвязь страницы сайта и виджета устанавливается посредством вызова нужных методов виджета и реагирования на события, генерируемые виджетом.

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

Подключение виджета
    
<div id="eShopLogisticStatic" data-key="[widget_key]" data-sort-door="sdek" data-sort-terminal="sdek"></div>
<script src="https://api.eshoplogistic.ru/widget/cart/v1/app.js"></script>
    

Где widget_key - ключ виджета из личного кабинета eShopLogistc.
Параметры data-sort-door и data-sort-terminal не обязательны; используются в случае желания установить какую-то определённую службу доставки по-умолчанию (т.е. будет выбрана автоматически при выборе соответствующего типа доставку (курьер или самовывоз)). По-умолчанию виджет выбирает вариант с наименьшей стоимостью.

Для старта виджету необходимы параметры:

  • offers - список товаров в корзине пользователя в json.
    Например:
    [{"article":"212","name":"212","count":"3","price":5895,"weight":3}, {"article":"67","name":"67","count":1,"price":114417,"weight":80}]
    В данном случае наименование товара (name) не имеет значения, но не должно быть пустым (требуется виджетом и может быть использовано в будущем). В строке offers для товаров может также присутствовать параметр габаритов dimensions.
  • city - данные о том куда доставлять и какие службы доступны для данного направления.
    Например:
    {"name":"Москва","type":"город","fias":"0c5b2444-70a0-4932-980c-b4dc0d3f02b5", "services":{"sdek":"44","delline":"7700000000000000000000000","dostavista":"0c5b2444-70a0-4932-980c-b4dc0d3f02b5","custom":"0c5b2444-70a0-4932-980c-b4dc0d3f02b5"}}
    При загрузке страницы эти данные могут быть получены в ответ на запрос к api.eshoplogistic.ru/api/target. В случае, если на сайте используется система определения местоположения пользователя, то в качестве параметра может быть передан ФИАС-код города или название города (не рекомендуется). В противном случае в запрос автоматически будет добавлен IP-адрес посетителя, и расположение будет определено по данному адресу. Если предварительное определение населённого пункта невозможно или не желательно, а также для изменения населённого пункта пользователем на сайте, используется метод api.eshoplogistic.ru/api/search.
  • payment - активный в данный момент ключ метода оплаты.
Методы виджета
  • load
    Инициализация виджета, обязательный метод, который должен быть вызван при загрузке страницы.
        
    // виджет
    const widget = document.getElementById('eShopLogisticStatic')
    
    // обязательно проверяем наличие необходимых данных, обрабатываем ошибки, если есть
    // ...
    // в результате у нас есть следующие условные объекты:
    // city: объект населённого пункта
    // delivery: активный способ доставки (не обязательно; варианты "door", "terminal", "postrf")
    // payment : объект выбранного варианта оплаты
    // offers: json-строка с товарами для расчёта доставки
    
    const city = {
           fias: "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
           name: "Москва",
           type: "город",
           services: { pecom: "446", postrf: "101000", sdek: "44" }
       },
       delivery = "door",
       offers = '[{ "article":"1","name":"Товар","count":"2","price":"300.25","weight":"2.4" }]',
       payment = { key: 'cashless' }
    
    // запускаем виджет
    widget.dispatchEvent(new CustomEvent('eShopLogistic:load',
        detail: {
           city: city,
           delivery: delivery,
           payment: payment,
           offers: offers
        }
    ))
        
    
  • reload
    Запускается аналогично load, но передаётся только тот параметр, который был изменён.
    Используется при необходимости перезапуска с новыми параметрами (например - изменился город, способ оплаты или состав корзины).
        
    // изменён способ оплаты (payment)
    // перезапускаем виджет
    widget.dispatchEvent(new CustomEvent('eShopLogistic:reload', {
       payment: { key: 'cash' }
    }))
        
    
События виджета

Ориентируясь на указанные ниже события необходимо выстраивать логику на странице оформления заказа. В response содержатся все необходимые данные.

Ключевые события:

  • onSelectedCity
    Возможно потребуется для подстановки выбранного города и штатные поля cms.
  • onSelectedService
    Фиксация выбора типа доставки вместе с сопутствующими данными: служба доставки, срок, цена.
  • onSelectedPVZ
    Выбор пункта самовывоза на карте.
  • onError
    Данные виджетом не получены, нужно показать пользователю сообщение или установить дефолтный способ доставки.

Все события:

    
document.addEventListener('eShopLogistic:ready', () => {

   eShopLogistic.onAddToCart = function (response) {
       console.log('Добавление в корзину:', response)
   }

   eShopLogistic.onChangeCountOffer = function (response) {
       console.log('Изменение количества в корзине:', response)
   }

   eShopLogistic.onChangeOptionOffer = function (response) {
       console.log('Изменение опции в корзине:', response)
   }

   eShopLogistic.onDestroyData = function () {
       console.log('Очистка введенных данных виджета')
   }

   eShopLogistic.onRemovePositionFromOffers = function (response) {
       console.log('Удаление предложения в корзине:', response)
   }

   eShopLogistic.onSelectedCity = function (response) {
       console.log('Выбор города:', response)
   }

   eShopLogistic.onSelectedPayment = function (response) {
       console.log('Выбор варианта оплаты:', response)
   }

   eShopLogistic.onSelectedService = function (response) {
       console.log('Выбор службы доставки:', response)
   }

   eShopLogistic.onSelectedTypeDelivery = function (response) {
       console.log('Выбор типа доставки:', response)
   }

   eShopLogistic.onClickButtonOrder = function (response) {
       console.log('Клик по кнопке «Заказать»', response)
   }

   eShopLogistic.onSubmitForm = function (response) {
       console.log('Отправка заказа:', response)
   }

   eShopLogistic.onSelectedPVZ = function (response) {
       console.log('Выбор ПВЗ', response)
   }

   eShopLogistic.onError = function (response) {
       console.log('Ошибка', response)
   }

   eShopLogistic.onDataUpdate = function (response) {
      console.log(`Данные с api`, response)
   }
})
    
Проброс событий виджета

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

    
eShopLogistic.onSelectedService = function (response) {
    // какие-то свои действия
    // ….
    //  передаем событие дальше
    document.dispatchEvent(
       new CustomEvent('esl2onSelectedService', { detail: response })
    )
}
    

Использование:

    
document.addEventListener('esl2onSelectedService', function(event) {
   console.log(event.detail)
})