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

О проекте

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

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

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

Содержание документа

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

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

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

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

Шаг 1. Выбор аккумуляторной системы

Шаг 2. Формирование заказа

Важно

Размер встраиваемого окна жестко фиксирован - ширина 936px, высота 600px. Адаптация UI под узкие экраны не предусматривается.

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

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

Внутрь iframe будут встроены инструменты сбора статистики - Google Analitics и Яндекс Метрика. С целью измерения эффективности работы конструктора. С последующим внесением изменений в его пользовательский интерфейс.

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

Шаг 1. Свяжитесь с представителем Bosch

Он занесет интернет-магазин в базу данных конструктора и выдаст уникальный 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=1600Z0002W+1600Z0002X+06015A1001
{
    // JSON response
    // Для каждого запрошенного кода заказа Bosch возвращается цена
    // товара, если он есть в наличии либо null
    '1600Z0002W': 4499,
    '1600Z0002X': 4619,
    '06015A1001': null, // этого товара нет в наличии
    // ...
}

Здесь '1600Z0002W+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=1600Z0002W+1600Z0002X+06015A1001
{
    // JSON response
    '1600Z0002W': {   // расширенный формат, вместо цены отдаем Object
      'price': 4499,  // обязательный атрибут
      'shops_id': 'GBA_10.8_V-LI_1.5', // артикул товарной позиции магазина
                                       // он не будет обработан конструктором
      'any_custom_property': 'some value',  // другой произвольный атрибут
      ...
    },
    '1600Z0002X': 4619, // короткий формат допустим как и в примере выше
    '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.

HTTPS вариант временно недоступен

Если вам необходимо HTTPS подключение - свяжитесь с администрацией конструктора Bosch.

Все загруженные 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: "06019B7300", // код заказа Bosch
    quantity: 1       // кол-во в корзине
  },
  {
    id: "06019B7301",
    quantity: 2
  },
  // ...
]

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

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

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

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

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

По организационным и прочим вопросам свяжитесь с менеджерами Bosch.

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