Интеграция Aplaut через JS-скрипт (Widgets 2.0)

План интеграции с установкой виджетов 2.0 и формы сбора отзывов на сайт с помощью JS-скрипта

Чек-лист перед началом интеграции

Пожалуйста, убедитесь, что у вас:

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

Интеграция. Подготовительные этапы

В разделе Команда ЛК Aplaut, созданного после заключения договора, добавьте коллег, которым необходим доступ на этапе интеграции, а также после нее.
Если до подключения Aplaut у вас были накоплены отзывы, импортируйте их, чтобы сохранить текущую картину по рейтингам и отзывам на сайте после интеграции.

Для этого подготовьте файл в одном из форматов: XLSX, CSV или JSONL:

Если у вас есть только отзывы (без комментариев/ответов от вашей команды или представителей брендов) и нет отзывов без текста (только оценка), рекомендуем использовать форматы XLSX или CSV, как наиболее простые в подготовке. Требования к файлу, а также инструкцию по импорту смотрите по ссылке.
Если у отзывов есть комментарии и ответы либо есть отзывы без текста, используйте формат JSONL. Каждая строка описывает один отзыв с комментариями, файл лучше сжать gzip. Формат описан на jsonlines.org, пример файла лежит на Google Drive, полный список полей — в разделе импорта.

Интеграция. Основные этапы

примечание

Работы по основному этапу могут выполняться параллельно с подготовительными. Это не должно тормозить интеграцию.

Синхронизация данных

1. Импорт каталога.

Важный элемент в платформе Aplaut — товар. Все основные процессы и почти все дополнительные завязаны на товаре. Поэтому важно обеспечить своевременную передачу и обновление данных о товарах, для этого в платформу импортируется каталог (фид):

Ознакомьтесь с требованиями к каталогу и подготовьте файл в необходимом формате;
Если у вас есть товары, у которых есть варианты и на сайте такие товары объединены в мультикарточки, группируйте товары в фиде чтобы отзывы на отдельный вариант товара отображались у всех;
Подготовьте прямую ссылку на файл фида для его скачивания и сохраните ссылку в настройках импорта, в ЛК Aplaut (поддерживается сжатие Gzip и Basic авторизация), а также включите Автоматическое скачивания файла.

2. Установка виджетов.

Установите базовую часть скрипта Aplaut (загрузчик) на все страницы сайта и поставьте теги виджетов туда, где они должны появиться. Подробнее — в инструкции по установке. Настройки виджетов подбираются в конструкторе виджетов.

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

3. Синхронизация рейтингов товаров с CMS.

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

Это позволит реализовать фильтр или сортировку товаров по рейтингу/кол-ву отзывов на сайте.

3.1 Экспорт дельты товаров.

Чтобы получить дельту обновленных товаров за определенный период, нужно создать задачу на экспорт, указав в параметрах соотвествующий фильтр.

Пример:

curl  -X POST \
  'http://api.aplaut.io/v4/export_tasks' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {APLAUT_TOKEN}' \
  --data-raw '{
  "data": {
    "type": "export_tasks",
    "attributes": {
      "records_type": "products",
      "search_options": {
        "filter": {
            "created_at": {
                "eq": "ГГГГ-ММ-ДД"
            }
        },
      },
      "format": "jsonl"
    }
  }
}'

Где {APLAUT_TOKEN} — ключ от Platform API (посмотреть можно в ЛК Aplaut, раздел Настройки → Разработчикам)

В ответе придёт ID задачи. Проверяйте её статус не чаще одного раза в минуту. Пример запроса:

curl 'https://api.aplaut.io/v4/export_tasks/{TASK_ID}' \
  -H 'Authorization: Bearer token={TOKEN}'

Пример ответа:

 {
  "data": {
    "id": "TASK_ID",
    "type": "export_tasks",
    "attributes": {
      "records_type": "products",
      "search_options": {
        "filter": {"created_at": {"eq": "ГГГГ-ММ-ДД"}},
      },
      "state": "completed",
      "refuse_reason": null,
      "error_message": null,
      "format": "jsonl",
      "export_format": null,
      "archive_url": "{ARCHIVE_URL}",
      "archive_size": 144696,
      "archive_content_type": "application/gzip",
      "created_at": "2023-11-03T17:00:41.353+03:00",
      "updated_at": "2023-11-03T17:14:53.529+03:00",
      "started_at": "2023-11-03T17:14:47.633+03:00",
      "finished_at": "2023-11-03T17:14:53.529+03:00"
    }
  }
}

Когда state=completed, параметр archive_url будет содержать URL c архивом файла экспорта.

Ограничения экспорта:

Существует квота на суммарное кол-во времени всех экспортов за день для всего аккаунта. По умолчанию 1 час в день;
Если квота превышена, то задачи на экспорт отклоняются сразу после старта задачи. Бесполезно дальше создавать следующие задачи;
Очень редко задача может "подвиснуть". Её статус никогда не станет completed. Если за 3 часа статус задачи не поменялся, считайте что она "подвисла". Создавайте новую;
Статус всех задач можно наблюдать в ЛК тут;
Такой способ синхронизации оптимизирует кол-во запросов, отправляемых в Aplaut, а также только так можно реализовать сортировку товаров и фильтрацию товаров на листинг-страницах сайта, т.к. параметры должны быть сохранены у товара в вашей БД.

Чек лист по основным этапам

Ссылка на каталог товаров в YML формате передана (поддерживается HTTP/FTP c Basic Auth) и включено автоматическое скачиваение
Скрипт установлен, добавлены DOM-элементы для виджетов
Рейтинги и кол-во отзывов товаров синхронизируются

Интеграция. Дополнительные этапы

Импортируйте заказы в Aplaut для запуска UGC-кампаний (email-кампании) по сбору отзывов после покупки. Есть два способа импорта, по постоянной ссылке на файл (раз в сутки, по аналогии с фидом), или по API.У импорта через файл есть два формата, ознакомьтесь с требованиями по ссылке.рекомендуем передавать уже выполненные заказы, где товар получен клиентом
Настройте DNS-записи, чтобы в письмах по UGC-кампаниям адрес отправителя был с вашим доменом и настройте шаблон письма (или подготовьте и отправьте нам собственный шаблон, если встроенные макеты вам не подходят по каким-то причинам):
Для настройки домена сообщите нам email и имя, которые хотите чтобы указывались в наших письмах, например "Компания N" n_company@yourdomain.ru.
Чтобы импортировать собственные шаблоны писем, ознакомьтесь с рекомендациями к шаблонам, чтобы учесть важные нюансы. Сверстайте и протестируйте его, и отправьте нам в виде файла формата html.
Добавьте кнопку "Оставить отзыв" в других частях сайта, чтобы дать возможность пользователям оставить отзыв не только в карточке товара, но и, например, в разделе с покупками/заказами клиента, если там есть список товаров, которые он приобретал. Для этого убедитесь, что на этих страницах также установлен скрипт Aplaut и стоит виджет отзывов или форма отзыва, и добавьте в обработчик клика по кнопке вызов:

aplaut.showReviewForm();

Товар для формы задаётся виджетом на странице или вызовом aplaut.setParams({ product_id: "<ID_ТОВАРА>" }). Подробнее — в справочнике JS API.

Настройте отправку событий по UGC-контенту во внешние системы (например системы лояльности) через вебхуки.

Чек-лист перед началом интеграции​

Интеграция. Подготовительные этапы​

Интеграция. Основные этапы​

Синхронизация данных​

Чек лист по основным этапам​

Интеграция. Дополнительные этапы​