Перейти на сайт

Интеграция Aplaut (Widgets API) / Пошаговый гайд

В документе описан пошаговый план интеграции платформы Aplaut, с использованием собственных виджетов и формы для сбора отзывов и комбинированным обменом данных (синхронно/асинхронно) по API.

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

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

  1. Заключен договор с Aplaut
  2. Создан аккаунт в платформе
  3. Есть выделенный специалист или команда для проведения интеграции

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

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

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

    1. Если у вас есть только отзывы (без комментариев/ответов от вашей команды или представителей брендов) и нет отзывов без текста (только оценка), рекомендуем использовать форматы XLSX или CSV, как наиболее простые в подготовке. Требования к файлу, а также инструкцию по импорту смотрите по ссылке.

    2. Если у отзывов есть комментарии/ответы, а также есть отзывы без текста, используйте формат JSONL (см. пример ниже).
      Пример формата для файла первоначального импорта отзывов.
      Файл предоставляется в формате JSONL(лучше сжатым gzip). Каждая строчка описывает один отзыв с комментариями.
      Пример файла.
      полный список полей можно посмотреть тут

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

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

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

Клиент <-> Aplaut

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

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

Клиент -> Aplaut

1. Для отправки отзывов из форм на сайте или в моб. приложении в Aplaut используйте Submissions API, метод "Создание отзыва" (см документацию).

2. Если вы хотите разрешить пользователям создавать отзывы без текста (только с рейтингом или рейтинг + фото/видео), необходимо активировать эту функцию через поддержку Aplaut (написав на support@aplaut.com, в телеграм @aplaut_support_bot или чат поддержки в ЛК), а также при передаче отзывов добавить атрибут wordless и значение true или false, соотв., если отзыв без текста и с текстом.

Как отправить отзыв с текстом через Submissions API?

curl -X POST https://s-api.aplaut.io/v2/reviews \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
  --data-raw '{
    "review": {
        "rating": 5,
        "wordless": false,
        "body": "Текст отзыва",
        "pros": "Текст поля Достоинства",
        "cons": "Текст поля Недостатки,
        "recommended": true,
        "author_id": "qwerty123",
        "author_name": "Манишева Рада Якимовна",
        "author_email": "youname@yourmail.ru",
        "author_phone": "79991112233",
        "location_name": "Уфа",
        "photo_urls": ["https://yoursite.ru/picture1.png", "https://yoursite.ru/picture1.png"],
        "photo_ids": ["8787258c9549834e99febf05", "8787258c9549834e99febf06"],
        "video_ids": ["654258c9549834e99febf05c"],
        "product_id": "178963",
        "author_ip": "178.214.291.62",
        "hide_my_data": false
     }
}'

Как отправить отзыв без текста через Submissions API:

    curl -X POST https://s-api.aplaut.io/v2/reviews \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
        "review": {
            "rating": 5,
            "wordless": true,
            "recommended": true,
            "author_id": "qwerty123",
            "author_name": "Иван",
            "author_email": "youname@yourmail.ru",
            "author_phone": "79991112233",
            "location_name": "Уфа",
            "photo_urls": ["https://yoursite.ru/picture1.png", "https://yoursite.ru/picture1.png"],
            "photo_ids": ["8787258c9549834e99febf05", "8787258c9549834e99febf06"],
            "video_ids": ["654258c9549834e99febf05c"],
            "product_id": "178963",
            "author_ip": "178.214.291.62",
            "hide_my_data": false
         }
    }'

Как отправить комментарий к отзыву через Submissions API:

    curl  -X POST https://s-api.aplaut.io/v2/reviews/{REVIEW_ID}/comments] \
      --header 'Accept: */*' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
      "comment": {
        "text": "Текст комментария на отзыв",
        "author_id": "qwerty123",
        "author_name": "Иван",
        "author_email": "yorname@yourmail.ru",
        "hide_my_data": true
      }
    }'

Как отправить комментарий к комментарию через Submissions API:

    curl  -X POST https://s-api.aplaut.io/v2/reviews/{REVIEW_ID}/comments] \
      --header 'Accept: */*' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
      "comment": {
        "text": "Текст комментария на комментарий",
        "parent_id": {REVIEW_ID},
        "external_parent_id": {REVIEW_EXTERNAL_ID}
        "author_id": "qwerty123",
        "author_name": "Иван",
        "author_email": "yorname@yourmail.ru",
        "hide_my_data": true
      }
    }'

список других полей можно посмотреть тут


Aplaut -> Клиент

1. Для отображения отзывов и рейтинга в карточке товара используйте Widgets API, метод Запрос одного виджета в формате JSON.

Пример запроса:

curl 'https://https://w-api2.aplaut.io/widgets/v2/render.json?authentication_token={APLAUT_TOKEN}&theme_id=default&context=product&context_id={OFFER.ID}&widget_id=product-reviews'

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

Пример ответа, а также описание атрибутов можно найти в документации, под параметрами запроса в блоке Responses.

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

Пример:

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

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

В ответе будет ID задачи, статут которой нужно проверять не чаще 1 раз в 1 минуту.
Пример запроса:

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

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

  1. Ссылка на каталог товаров в YML формате передана (поддерживается HTTP/FTP c Basic Auth) и включено автоматическое скачиваение;
  2. На листинг-страницах и в карточках товаров реализованы собственные виджеты, а также настроен обмен данными по Submissions API и Widgets API для отправки и получения отзывов и рейтингов;
  3. Рейтинги и кол-во отзывов товаров синхронизируются.

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

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


Справочная информация

  1. База знаний
  2. Документация Widgets API
  3. Документация Submissions API


👆 На этом пока всё