Перейти к основному содержимому

Подключение Aplaut к сайту или другой платформе

План подключения Aplaut: что подготовить, как загрузить каталог и вывести отзывы через JS-скрипт, Widgets API или Platform API, как синхронизировать рейтинги и события

Интеграция с Aplaut состоит из общих шагов и одного шага, который зависит от способа. Подготовка кабинета, каталог товаров, синхронизация рейтингов и дополнительные настройки одинаковы для всех. Различается то, как отзывы попадают на сайт:

СпособЧто стоит на сайтеКак отзывы попадают на сайт и в Aplaut
JS-скриптГотовые виджеты Aplaut 2.0Виджеты сами загружают отзывы и отправляют новые из своей формы
Widgets APIВаши виджеты и форма отзываОтзывы и рейтинг товара сайт запрашивает из Widgets API, новые отзывы отправляет через Submissions API
Platform APIВаши виджеты и форма отзыва, без запросов к Aplaut со страницыОтзывы и рейтинги сайт забирает на бэкенде по расписанию, новые отправляет через Submissions API

Выбранный способ переключается на вкладках в шагах 3 и 6. Вкладки связаны: выбор на одной меняет и остальные.

Что нужно перед началом​

  • Договор с Aplaut.
  • Аккаунт в личном кабинете Aplaut.
  • Разработчик или команда, которые проведут интеграцию.
  • Если отзывы собирались до подключения Aplaut, их выгрузка в файл.

Шаг 1. Подготовьте кабинет и перенесите отзывы​

  1. В личном кабинете в разделе Админ → Аккаунт → Команда добавьте коллег, которым нужен доступ во время интеграции и после неё: см. как пригласить пользователя. Приглашать коллег может пользователь с ролью Администратор.
  2. Если до подключения Aplaut у вас накопились отзывы, импортируйте их. Тогда рейтинги и отзывы на сайте сохранятся после интеграции. Подготовьте файл в одном из форматов:
    • XLSX или CSV, если у вас только отзывы, без комментариев и ответов вашей команды, и нет отзывов без текста. Требования к файлу и порядок импорта — в статье «Импорт данных в кабинете».
    • JSONL, если у отзывов есть комментарии и ответы или есть отзывы без текста. Каждая строка описывает один отзыв с комментариями, файл лучше сжать gzip. Формат описан на jsonlines.org, пример файла лежит на Google Drive, полный список полей — в разделе импорта.

Шаги 2–5 можно выполнять параллельно с первым: перенос отзывов не задерживает остальную интеграцию.

Шаг 2. Подключите каталог товаров​

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

  1. Подготовьте файл каталога по требованиям к каталогу.
  2. Если варианты товара на сайте объединены в одну карточку, сгруппируйте их в фиде. Тогда отзыв на один вариант будет виден у всех.
  3. Сохраните прямую ссылку на файл в настройках импорта и включите автоматическое скачивание. Aplaut поддерживает HTTP и FTP, сжатие gzip и Basic-авторизацию.

Шаг 3. Выведите отзывы на сайт​

  1. Установите загрузчик скрипта Aplaut на все страницы сайта и поставьте теги виджетов (<ap-reviews>, <ap-informer> и другие) туда, где они должны появиться: см. инструкцию по установке. Перечислять виджеты в aplaut.init не нужно: виджет загружается, когда его тег появляется на странице.
  2. Подберите настройки виджетов в конструкторе виджетов. Конструктор доступен в раннем доступе или по запросу к менеджеру Aplaut.
  3. Если оставлять отзывы могут только покупатели, которые вошли на сайт, настройте вход покупателя. Если только купившие товар — проверку покупки. По умолчанию виджеты не связаны с CMS и другими вашими системами.

Новые отзывы виджеты отправляют в Aplaut сами, Submissions API для этого не нужен.

Шаг 4. Синхронизируйте рейтинги с сайтом​

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

Раз в сутки забирайте товары, которые изменились за прошедший день, периодическим экспортом. Запросы к Platform API подписывайте токеном OAuth-приложения с доступом Platform API: см. как получить токен доступа к API. Способы передачи токена — в справочнике группы «API и доступы».

  1. Создайте задачу на экспорт с фильтром по дате изменения:

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

    Для интеграции через Platform API создайте такую же задачу с "records_type": "reviews": она вернёт новые и изменённые отзывы за день.

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

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

  3. Когда в ответе state равен completed, скачайте архив по ссылке из archive_url:

    {
      "data": {
        "id": "TASK_ID",
        "type": "export_tasks",
        "attributes": {
          "records_type": "products",
          "state": "completed",
          "format": "jsonl",
          "archive_url": "{ARCHIVE_URL}",
          "archive_size": 144696,
          "archive_content_type": "application/gzip",
          "finished_at": "2023-11-03T17:14:53.529+03:00"
        }
      }
    }

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

  • У компании есть суточная квота на суммарное время экспортов, по умолчанию 60 минут, общая для кабинета и API: см. справочник лимитов экспорта. Когда квота исчерпана, новые задачи встают в очередь с низким приоритетом и выполняются дольше. Не создавайте повторную задачу, дождитесь уже созданной.
  • Изредка задача зависает, и её статус не становится completed. Если статус не менялся 3 часа, создайте новую задачу.
  • Статус всех задач виден в кабинете в журнале Журналы → Экспорт данных.

Если изменения нужны чаще раза в сутки, используйте один из двух способов:

  • Обход данных через Platform API: GET /v4/scroll/{reviews|products|questions} с курсором отдаёт записи, изменённые после заданной даты, постранично и без квоты экспорта. Сводку отзывов товара запрашивайте через include=reviews_summary_item: атрибута summary у товара нет.
  • Исходящий вебхук: Aplaut отправляет событие на ваш URL при создании, изменении, публикации или бане отзыва, комментария, вопроса или ответа, а также при пересчёте рейтинга товара. Вебхук настраивается в кабинете в разделе Инструменты → Интеграции. Список событий и примеры тела — в справочнике событий вебхуков.

Шаг 5. Отправляйте отзывы через Submissions API​

Шаг нужен для интеграции через Widgets API и Platform API. При интеграции через JS-скрипт новые отзывы отправляет форма виджета.

Отзывы из форм на сайте или в мобильном приложении отправляйте методом «Создание отзыва» Submissions API. Запросы подписывайте токеном OAuth-приложения с доступом Submissions API.

Отзывы без текста, только с оценкой или с оценкой и фото, по умолчанию выключены. Чтобы их принимать, попросите поддержку Aplaut включить функцию: напишите на support@aplaut.com, в Telegram @aplaut_support_bot или в чат поддержки в личном кабинете. В каждом отзыве передавайте wordless: true для отзыва без текста, false для отзыва с текстом.

curl -X POST https://s-api.aplaut.io/v2/reviews \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {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/picture2.png"],
      "photo_ids": ["8787258c9549834e99febf05", "8787258c9549834e99febf06"],
      "video_ids": ["654258c9549834e99febf05c"],
      "product_id": "178963",
      "author_ip": "178.214.291.62",
      "hide_my_data": false
    }
  }'

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

Шаг 6. Проверьте основные этапы​

  • Ссылка на каталог сохранена в настройках импорта, автоматическое скачивание включено.
  • Загрузчик установлен на всех страницах, теги виджетов <ap-…> стоят на нужных страницах.
  • Рейтинги и число отзывов товаров синхронизируются с сайтом.

Дополнительные этапы​

  1. Импортируйте заказы, чтобы запускать email-кампании по сбору отзывов после покупки. Передавайте выполненные заказы, по которым покупатель уже получил товар. Импортировать заказы можно по постоянной ссылке на файл раз в сутки, как каталог, или через API. Форматы файлов — в справочнике форматов импорта.

  2. Настройте отправку писем с вашего домена. Сообщите менеджеру Aplaut имя и адрес отправителя, например «Компания N» и n_company@yourdomain.ru, и добавьте DNS-записи, которые он пришлёт. Если встроенные шаблоны писем не подходят, сверстайте свой по требованиям к шаблонам писем, проверьте его и отправьте менеджеру файлом HTML.

  3. Добавьте кнопку Оставить отзыв на другие страницы сайта, например в список заказов покупателя. При интеграции через JS-скрипт на такой странице должны стоять загрузчик и виджет отзывов или форма отзыва, а по клику на кнопку вызывайте:

    aplaut.showReviewForm();

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

  4. Передавайте события по отзывам и вопросам во внешние системы, например в программу лояльности, через исходящий вебхук. Список событий и формат тела — в справочнике событий вебхуков.

  5. При интеграции через Widgets API можно показать галерею фото и видео из отзывов. По умолчанию она выключена, включает её менеджер Aplaut. Медиа вместе с отзывами отдаёт render.json с параметром gallery=true, отдельно от списка — запрос /gallery. Для постраничного превью только с медиа используйте /gallery с preview=true и параметром page. Чтобы первыми шли медиа из отзывов с высокой оценкой, попросите менеджера включить сортировку по оценке и передайте sort=score:desc в /gallery или gallery_sort=score:desc в render.json. Без этого у всех элементов галереи одинаковый score. Видео Kinescope встраивайте по kinescope_assets.external_id плеером Kinescope, адрес видео имеет вид https://kinescope.io/embed/{external_id}. Поля ответа — в справочнике Widgets API.

Справочники API​