Виджет

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

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

§ Настройки виджета

• Общие
• Отправка заказа
• Названия и сообщения
• Корзина
• Подключение

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

§ Простой виджет расчтёта стоимости и срока доставки

    
    <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-атрибуты.
Эти атрибуды предназначены для переопределения настроек виджета для данной страницы/кнопки без изменения настроек в Личном кабинете.

• Глобальные (для <div id="eShopLogisticApp"></div>).
  Определяют параметры запуска виджета на данной странице.
• Локальные (для конкретной кнопки запуска виджета).
  Определяют параметры запуска виджета для данной кнопки.

Отправка заказов в 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":"Заказ отправлен!" // текстовое сообщение для виджета (может быть пустым)
    }
    

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

    
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)
    }
})      
    

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

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

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

Описание

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

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

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

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

Подключение виджета

    
<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)
})