Руководство по подключению

Раздел описывает основные шаги для подключения сервисов Aplaut на ваш сайт.

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

1. Предварительные требования

Каждый товар, который вы продаете, должен иметь уникальный идентификатор - product_id. Данный идентификатор должен быть:

1. Равен xml аттрибуту offer.id из YML каталога, который вы импортируете.
2. Передаваться в заказах через параметр product_id.
3. Доступен в карточках товара на вашем сайте для инициализации скрипта app.js.

WARNING

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

2. Импорт каталога товаров

Каталог товаров автоматически скачивается по ссылке на файл в формате YML один раз в день в 02:00 AM. Подготовьте YML файл и ознакомьтесь с нашими требования к каталогу.

TIP

Если вы зарегистрированы на Яндекс.Маркет, вы можете загрузить к нам фид, который вы уже подготовили для данной площадки.

Перейдите в ЛК Настройки → Импорт данных → Импорт каталога, укажите ссылку, по которой ваш каталог будет доступен, сохраните настройки и нажмите на кнопку ИМПОРТИРОВАТЬ СЕЙЧАС

Начнется импорт каталога товаров. Результаты вы сможете проверить в журнале событий.

TIP

Если каталог не доступен по публичной ссылке, вы можете загрузить его ЧЕРЕЗ ФАЙЛ.

3. Публикация виджетов

Допустим на вашем сайте, имеется:

• листинг с товарами (например, категория)
• карточка товара

Карточка товара

Допустим, на странице товара планируется добавить два виджета:

• Отзывы о товаре
• Рейтинг товара (звездочки и кол-во отзывов)

Чтобы виджеты появились на странице, необходимо выполнить следующие действия:

1. Настроить виджеты в ЛК (например, кол-во отзывов в виджете, критерии для сортировки отзывов и т.д)
2. В те места страницы, где должны появится виджеты, добавить DOM контейнеры.
3. В код загрузчика скрипта app.js добавить команды

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

В личном кабинете в разделе Виджеты проверьте наличие виджетов:

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

• product-reviews — отзывы о товаре
• inline-rating — рейтинг товара (звездочки и кол-во отзывов)

Добавление DOM контейнеров

Пример добавления DOM контейнеров на страницу Карточка товара:

Как показано на картинке, добавьте в шаблон страницы Карточка товара два пустых контейнера:

• <div id='sp-product-reviews-container'/> — отзывы о товаре
• <div id='sp-inline-rating-container' /> — рейтинг товара

Команды скрипта добавления виджетов

В код загрузчика скрипта app.js, добавьте следующие команды загрузчика:

<script>
  (function() {
    window._shoppilot = window._shoppilot || [];

    // Стили
    _shoppilot.push(['_addStyles', 'widgets']);

    // Идентификатор товара в карточке товара
    _shoppilot.push(['_setProductId', '<?= PRODUCT_ID ?>']);

    // Команды для отображения виджетов
    _shoppilot.push(['_addProductWidget',
        'product-reviews', '#sp-product-reviews-container']);
    _shoppilot.push(['_addProductWidget',
        'inline-rating', '#sp-inline-rating-container']);

    // Загрузчик скрипта
    var store_id = '<?= STORE_ID ?>';
    var theme_id = 'default';
    var script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.src = '//get.shoppilot.ru/f/v1/'
      + store_id + '/' + theme_id + '/app.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(script, s);
  })();
</script>

Комментарии:

• PRODUCT_ID — идентификатор товара (offer.id из YML файла).
• STORE_ID — идентификатор витрины вашего интернет-магазина (cм. в ЛК).

Листинги

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

Чтобы виджеты появились на странице, необходимо выполнить следующие действия:

1. Настроить виджет в ЛК (см. выше)
2. В те места страницы, где должны появится виджеты, добавить DOM контейнеры.
3. В код загрузчика скрипта app.js добавить команды

Добавление контейнеров

Как показано на картинке, для каждого товара добавьте в шаблон листинга пустые контейнеры с id = sp-inline-rating-PRODUCT_ID, где PRODUCT_ID — идентификатор продукта. (offer.id в YML файле).

Команды для отображения виджетов

Скопируйте и установите код на свой сайт сразу после открывающего тега <body>:

<script>
  window._shoppilot = window._shoppilot || [];
  _shoppilot.push(['_addStyles', 'widgets']);
</script>

Далее для каждого товара на странице необходимо добавить команду: _addProductWidget

<? foreach($products as $product): ?>
<div class="product">
  <div class="product-name"><?= $product->name ?></div>
  <div class="product-price"><?= $product->price ?></div>
  <div
    class="product-rating"
    id="sp-inline-rating-<?= $product->id ?>"></div>
  <script>
    _shoppilot.push([
      '_addProductWidget',
      'category-inline-rating',
      '#sp-inline-rating-<?= $product->id ?>',
      { product_id: '<?= $product->id ?>' }
    ]);
  </script>
</div>
<? endforeach; ?>

После добавьте загрузчик скрипта:

<script>
  (function() {
    var store_id = '<?= STORE_ID ?>';
    var theme_id = 'default';
    var script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.src = '//get.shoppilot.ru/f/v1/'
      + store_id + '/' + theme_id + '/app.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(script, s);
  })();
</script>

Комментарии к скрипту:

• STORE_ID — идентификатор витрины вашего интернет-магазина (cм. в ЛК).

WARNING

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

4. Импорт отзывов Опционально

Подготовьте CSV (кодировка UTF-8) или XLSX файл в следующем формате:

№	Название	Обязательно	Описание
1	author_email		Email автора
2	author_name	Да	Имя автора
3	rating	Да	Рейтинг
4	pros	Да	Текст с преимуществами
5	cons	Да	Текст с недостатки
6	body	Да	Текст комментария
7	product_id		Идентификатор товара (offer.id из YML)
8	tag_names		Список тегов
9	created_at		Дата создания (2021-01-01 00:11:22)

Комментарии:

• Порядок колонок не важен, но первая строка должна содержать названия колонок.
• Остальные колонки (> №9), будут считаться пользовательскими атрибутами (custom_attributes).
• Скачать пример

Перейдите в раздел Настройки → Импорт данных → Отзывы. Выберите файл с отзывами и нажмите ИМПОРТИРОВАТЬ.

Начнется импорт отзывов. Результаты вы сможете проверить в журнале событий.

TIP

Отзывы также можно передать, используя Platform API v4. Так вы сможете передать больше данных об отзыве, чем через файл. Например, сможете передавать детали рейтинга, или детали автора (cм. описание API)

5. Импорт заказов Опционально

Передача заказов позволит вам настроить кампании для автоматического сбора отзывов от покупателей.

Подготовьте CSV (кодировка UTF-8) или XLSX файл в следующем формате:

№	Название	Обязательно	Описание
1	number	Да	Уникальный номер заказа
2	consumer_email	Да	Email клиента
3	consumer_name	Да	Полное имя клиента
5	product_ids	Да	Список ID товаров в корзине (offer.id из YML)

Комментарии:

• Порядок колонок не важен, но первая строка, должна содержать названия колонок.
• В качестве разделителя списка ID товаров в корзине - "|" (например: 12232|32343|76348)
• Остальные колонки (> №5), будут считаться дополнительными параметрами заказа (поле details объекта заказ). Например, так можно передать статус оплаты (payment_status) или статус доставки (fullfilment_status).
• Скачать пример

TIP

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

Перейдите в раздел Настройки компании → Импорт данных → Заказы. Выберите файл с заказами и нажмите ИМПОРТИРОВАТЬ.

Начнется импорт заказов. Результаты вы сможете проверить в журнале событий.

TIP

Чтобы автоматизировать импорт заказов, используйте

• Platform API или
• Ежедневные выгрузки на FTP (см. импорт заказов)