Bosch Power Tools Builder
Инструкция по подключению

О проекте

Проект Bosch Power Tools Builder - это интерактивный конструктор электроинструментов Bosch, встраиваемый на отдельную страницу интернет-магазина. Конструктор наглядно демонстрирует финансовую выгоду от приобретения электроинструментов одного семейства, помогает покупателю собрать свой набор, подобрать аккумуляторы и зарядные устройства. Сформированный заказ из выбранных электроинструментов передается интернет-магазину.

Важно отметить, что настоящий проект не является интернет-магазином. Он не пытается и не планирует повторять его функционал, возможности. Главная цель проекта - помочь покупателю разобраться в линейке продукции Bosch, донести до потребителя принцип системности продуктов Bosch, помочь сформировать заказ. По этой причине контструктор не планирует решать следующие задачи:

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

Описание архитектуры

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

Конструктор оформлен по-разному для DIY и PRO линеек инструмента Bosch. Пример того, как выглядит конструктор:

Формирование заказа Формирование заказа

Важно

Когда конфигуратор работает в десктопном режиме, он встраивается в окно фиксированного размера: ширина 936px, высота 600px.

Когда конфигуратор работает в мобильном режиме, окно конфигуратора раскрывается на полный экран.

На посадочной странице размещается iframe. Взаимодействие с ним и его настройка происходит при помощи JavaScript API. Настройки включают в себя: место встраивания iframe в документ, цены интернет-магазина, наличие товаров и пр. Подробности указаны ниже.

С кнопкой "Оформить заказ" связан код магазина (callback), в который передается список выбранных пользователем товаров. JavaScript со стороны интернет-магазина добавляет выбранные покупателем товары в корзину интернет-магазина и уводит пользователя на страницу окончательного оформления заказа.

Действия пользователя внутри iframe конструктора записываются с помощью Google Analytics и Яндекс Метрики. Эти данные позволяют нам дорабатывать и совершенствовать пользовательский интерфейс.

Важно

Google Analytics и Яндекс Метрика собирают действия пользователя только внутри конфигуратора и ничего не узнают о том, как пользователи взаимодействуют с магазином. Ваш сайт изолирован от них с помощью iframe.

Как подключать

Шаг 1. Свяжитесь с нами

Свяжитесь с нами по адресу bpt_builder@levelupdev.com

Мы занесем интернет-магазин в базу данных конструктора и выдадим уникальный url для загрузки JavaScript API.

Шаг 2. Создайте посадочную страницу для отображения конструктора

В интернет-магазине нужно завести специальную страницу на которой будет размещен конструктор Bosch Power Tools. Пример:

<html>
  <body>
    <div id="container_id"></div>
  </body>
</html>

В примере выше создан контейнер <div id="container_id"> для последующего размещения в нем iframe конструктора. В десктопном варианте, конструктор будет отображаться в этом месте.

Обратите внимание на большую фиксированную ширину десктопного конструктора - 936px. Схема верстки страницы должна позволять размещение столь большого блока.

Шаг 3. Создайте специальный url для подгрузки цен магазина

При каждом отображении конструктора пользователю у магазина будут запрошены цены на электроинструменты Bosch. Такая схема позволяет, в частности, отображать разные цены в зависимости от местонахождения покупателя либо его персональных условий/скидок.

На указанный url магазина конструктор будет отправлять AJAX GET запросы следующего вида:

$ curl http://shop.com/get_bosch_pt_prices?ids=1600A00X79+1600Z0002X+06015A1001
{
    // JSON response
    // Для каждого запрошенного кода заказа Bosch возвращается цена
    // товара, если он есть в наличии либо null
    "1600A00X79": 2660,
    "1600Z0002X": 2090,
    "06015A1001": null, // этого товара нет в наличии
    // ...
}

Здесь 1600A00X79+1600Z0002X+06015A1001 - это коды заказа Bosch Power Tools, разделенные пробелом (знак + в url). Такой формат записи выбран в связи с ограничением на размер GET запроса.

Запрос по указанному url магазина может быть автоматически разбит конструктором на несколько запросов. С разными наборами ids. Решение принимается исходя из количества ids. См. подробное описание настроек конструктора.

Конструктор также "понимает" расширенный формат ответа сервера интернет-магазина. В нем вместо цены для артикула Bosch может быть указан Object с одним обязательным атрибутом - price - и произвольным количеством других атрибутов. Все они без изменений будут переданы в onsubmit callback. Например, для каждого артикула Bosch с сервера на client-side можно передать внутренний артикул интернет-магазина. Затем использовать его для наполнения корзины интернет-магазина. Подробнее этот пример рассмотрен далее по тексту.

Полный пример запроса к серверу и ответа на него:

$ curl http://shop.com/get_bosch_pt_prices?ids=1600A00X79+1600Z0002X+06015A1001
{
    // JSON response
    "1600A00X79": {   // расширенный формат, вместо цены отдаем Object
      "price": 2660,  // обязательный атрибут
      "shops_id": "GBA_12_3", // артикул товарной позиции магазина
                                       // он не будет обработан конструктором
      "any_custom_property": "some value",  // другой произвольный атрибут
      ...
    },
    "1600Z0002X": 2090, // короткий формат допустим как и в примере выше
    "06015A1001": null, // этого товара нет в наличии
    // ...
}

Замечание

При большом количестве покупателей на сайте AJAX запросы цен магазина могут значительно увеличить нагрузку на сервер. Рекомендуется кешировать на сервере ответ на несколько секунд с учетом значения GET параметра ids, если это возможно.

Шаг 4. Подключите JavaScript API

В простейшем виде это можно сделать так:

<html>
  <head>
    <script src="//builder.bpt.levelupdev.ru/builder/shop/DIY.min.js" type="text/javascript"></script>
  </head>
</html>

Часть адреса shop/DIY является уникальной для каждого подключенного интернет-магазина и конструктора. См. первый шаг инструкции.

Полный формат записи URL выглядит следующим образом:

(http|https)://builder.bpt.levelupdev.ru/builder/shop/DIY(.min).js?(ns=bpt_builder)(&init=init_callback)

Файл может быть загружен как по протоколу HTTP, так и по HTTPS.

Все загруженные JavaScript объекты принадлежат пространству имен, указанному в GET параметре ns. По умолчанию - это bpt_builder.

Если указан GET параметр init, то по завершению загрузки JavaScript API будет вызвана соответствующая функция. В примере выше - это window.init_callback(). Эта возможность полезна при асинхронной загрузке JS API. В противном случае её использовать не обязательно.

Важно

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

Шаг 5. Создайте конструктор

С использованием Javasctipt API инициализируйте конструктор на посадочной странице. Например, так:

<script type="text/javascript">
  var builder = new bpt_builder.Builder({
    el: 'container_id', // id DOM элемента для размещения конструктора
    prices_url: '/get_bosch_pt_prices/', // url для загрузки цен магазина
    onsubmit: function(basket, shop_catalog){
      // callback оформления заказа
      // TODO add basket items to basket of the host shop before redirect made
      window.location="/order/";
    }
  });
</script>

В примере выше не реализовано наполнение корзины интернет-магазина выбранными покупателем электроинструментами. Этот код специфичен для каждого магазина и должен быть реализован программистом со стороны магазина.

Конфигурация конструктора

Ниже приведено подробное описание каждого параметра конфигурации bpt_builder.Builder.

el

Id DOM элемента для размещения внутри него iframe конструктора. Вместо id можно указать сам элемент DOM.

prices_url

Обязательный аргумент если используется стандартный метод request_prices. Это специальный url для загрузки цен магазина. Создается программистом со стороны интернет-магазина.

request_prices( ids, callback )

Функция, вызываемая конструктором для запроса цен и наличия у интернет-магазина. По умолчанию, делает AJAX запрос по адресу указанному в prices_url, конвертирует JSON ответ в JavaScript object и передает его в callback.

Если вам необходимо передать на сервер дополнительные параметры либо использовать JSONP - вы можете переопределить данную функцию.

ids_per_request

Максимальное количество ids для которых конструктору разрешено запросить цены у интернет-магазина одним AJAX запросом. В случае превышения ограничения конструктор разбивает один AJAX запрос на несколько. Значение по умолчанию - 50.

onsubmit( basket, shop_catalog )

Обязательный аргумент. Это callback функция. Вызывается конструктором по нажатию на кнопку "Оформить заказ".

Предназначена для передачи заказа из конструктора внутрь интернет-магазина.Формат данных basket:

basket = [
  {
    id: "06019F1101", // код заказа Bosch
    quantity: 1       // кол-во в корзине
  },
  {
    id: "06019E9100",
    quantity: 2
  },
  // ...
]

shop_catalog имеет в точности такой же формат данных, как и ответ сервера интернет-магазина на запрос к prices_url. В частности, если для каждого товара с сервера был передан внутренний артикул интернет-магазина, то здесь этим можно воспользоваться, облегчив наполнение корзины интернет-магазина.

Простой пример реализации callback функции. В данном примере сразу происходит переход на страницу корзины магазина, корзина получает информацию о добавляемых товарах через GET параметры, shop_catalog не используется:

  function(basket, shop_catalog){
    window.location="/cart?add="+JSON.stringify(basket);
  }

border

Флаг управляющий поведением iframe CSS border.

Значение Описание
true Десктопная версия конструктора обрамляется тонкой черной рамкой. Значение по умолчанию
false Конструктор отображается без рамки

Дополнительные требования к магазину

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

Обратная связь

По всем техническим вопросам, замечаниям и предложениям обращайтесь по адресу bpt_builder@levelupdev.com