Создание PWA и подключение таблиц Метабот

PWA — веб-приложение, которое можно установить на устройство. Интерфейс можно сделать на React, а данные сохранять в кастомных таблицах Метабот через API.

Как работает приложение

В этой инструкции мы создадим веб-приложение (PWA), которое пользователь сможет открыть в браузере или установить на смартфон.

Приложение будет передавать введённые пользователем данные в Metabot через API. Metabot обработает полученную информацию и сохранит её в кастомной таблице.

Для этого необходимо:

Создать интерфейс веб-приложения.
Настроить возможность установки приложения на устройство.
Подготовить таблицу для хранения данных в Metabot.
Настроить API для передачи информации.
Проверить работу приложения и сохранение данных.
Разместить готовое приложение на сервере.

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

API — это механизм взаимодействия между приложениями. PWA отвечает за пользовательский интерфейс, а Metabot — за обработку и хранение данных. Для безопасного обращения к защищённому API используется серверная часть, на которой хранится API-токен.

Перед началом работы

Для разработки и подключения PWA потребуется:

Node.js и npm — для создания проекта и сборки приложения.
Редактор кода — например, Visual Studio Code.
Доступ к Metabot — к боту, в котором будут храниться данные.
Технические названия таблиц и полей — для настройки обмена данными.
Postman или Swagger — для проверки API-запросов.
Сервер с HTTPS — для размещения готового приложения.
Домен — если приложение должно открываться по отдельному адресу заказчика.

Разработкой интерфейса занимается разработчик приложения. Настройка доступа к API и публикация приложения на инфраструктуре Metabot выполняются по согласованию с командой Metabot.

Если вам необходимо создать API-пользователя или разместить приложение на сервере Metabot, обратитесь в техническую поддержку или к вашему менеджеру проекта.

Создать приложение

Для небольшого приложения подойдёт React с Vite. Создать проект можно командой:

npm create vite@latest my-pwa -- --template react-ts

React — библиотека для создания пользовательского интерфейса. Vite — инструмент, который помогает создать проект, запустить его для разработки и подготовить файлы для публикации.

После создания проекта необходимо перейти в папку приложения, установить зависимости, разработать интерфейс (страницы, формы, расчёты и обработку отправки данных) и запустить локальный сервер разработки.

cd my-pwa
npm install
npm run dev

На этом этапе приложение работает на компьютере разработчика. Оно ещё не опубликовано в интернете и не подключено к Metabot.

Документация: React, создание проекта Vite.

Добавить PWA

Для установки приложения на устройство используются:

Manifest — файл с названием приложения, иконками, стартовым адресом и настройками отображения.
Service worker — механизм браузера, который позволяет кешировать файлы приложения и реализовывать отдельные функции без подключения к интернету.
HTTPS — защищённое соединение, необходимое для работы PWA на опубликованном сайте.

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

Для Vite можно использовать vite-plugin-pwa. В настройках указать название приложения, иконки 192×192 и 512×512, стартовый адрес и режим отображения standalone. Настроить service worker для кеширования файлов приложения и работы без сети.

Разместить приложение на хостинге с HTTPS. Проверить установку на телефон, запуск с иконки и обновление приложения. Запись в Метабот требует подключения к интернету; сохранение и повторную отправку данных без сети нужно реализовывать отдельно.

Документация: подключение PWA к Vite, основы PWA.

Создать таблицу в Метабот

В нужном боте открыть «Таблицы», нажать «Создать» и указать техническое имя таблицы, например bmi.

В разделе «Структура» добавить поля и выбрать их типы. Имена таблиц и полей задаются строчными латинскими буквами, цифрами и подчёркиваниями. После настройки нажать «Обновить все поля в БД».

Названия полей в отправляемом объекте data должны совпадать с техническими именами полей таблицы.

Документация: кастомные таблицы.

Создать API-пользователя

В разделе «Пользователи бизнеса» создать пользователя, включить «Пользователь API», указать имя, роль и доступ к нужному боту. Нажать «Сгенерировать API-токен» и скопировать токен.

Для создания пользователя API обратитесь в поддержку Metabot

Для авторизации запросов используется заголовок:

Authorization: Bearer <API_TOKEN>

Документация: конструктор API, раздел о генерации токена.

Настроить запись в таблицу

В настройках бота открыть «Внутреннее API» и создать активную конечную точку. Например алиас user_events, метод POST, формат JSON.

Этот обработчик получает data и создаёт запись:

let item = table.createItem("user_events", {
  session_id: data.session_id,
  event_type: data.event_type
});

Адрес конечной точки: https://<адрес-платформы>/api/v1/bots/<bot_id>/call/user_events

Тело запроса для обработчика:

{ 
  "script_request_params": { 
      "data": { 
        "session_id": "123", 
        "event_type": 24.5 
      } 
  } 
}

Обёртка script_request_params нужна для доступа к этим данным через request.json в обработчике Метабот.

Отправлять запрос методом POST с заголовками Content-Type: application/json и Authorization. В публичном PWA запрос лучше выполнять через свой сервер: API-токен хранить на сервере, чтобы он не попадал в код браузера.

Документация: вызов внутреннего API.

Проверить подключение

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

1. Проверка API

Откройте Swagger Metabot по адресу /api/docs либо используйте Postman.

Отправьте тестовый запрос с корректным токеном и параметрами. Убедитесь, что сервер возвращает успешный ответ.

2. Проверка записи в таблицу

Откройте нужный бот в Metabot, перейдите в раздел «Таблицы» и выберите таблицу, в которую отправляли данные.

Проверьте, что новая запись появилась и значения полей совпадают с отправленными.

3. Проверка PWA

Откройте приложение, заполните форму и отправьте данные.

Убедитесь, что приложение получает подтверждение записи и корректно показывает пользователю результат операции.

Если запись не появилась

Проверьте техническое имя таблицы, названия полей, разрешённый список allowedTables, права API-пользователя, адрес конечной точки, наличие токена и структуру JSON.

При ошибках авторизации проверьте действительность токена и доступ пользователя к боту.

При ошибках передачи данных проверьте параметры запроса и серверные журналы.

Важно: запросы из Swagger и Postman создают реальные записи в таблицах. Для проверки используйте тестовые данные.

Build и размещение на сервере (+настройка домена)

После окончания разработки и проверки функциональности необходимо подготовить приложение к размещению на сервере.

Для проекта на Vite выполните команду:

npm run build

В результате в папке dist появятся файлы готового приложения.

dist — это результат сборки проекта, который обычно содержит HTML, CSS, JavaScript, изображения и другие необходимые ресурсы.

Важно: исходный React-проект и готовая сборка — не одно и то же.

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

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

После билда у вас в папке dist будут файлы, которые нужно перенести на сервер. Далее есть 2 развития событий:

Размещение на домене заказчика не требуется. Подбираем сервер и заливаем в папку forms/ платформы в папку проекта (допустим forms/testsite) все файлы из dist
Если требуется размещение на домене заказчика. Нужно подобрать сервер, где не установлена платформа или самый свободный. Создать в var/www/ папку проекта. Залить туда файлы из dist. Настроить nginx на домен который предоставил заказчик. После этого передать заказчику IP сервера и попросить создать A/AAA запись в DNS. Подождать пока обновятся DNS сервера (это может занять от 5 минут до 3 суток), нужно переодически проверять доступность сайта по домену. Далее при необходимости получить сертефикат. Сертефикат требуется для https:// соединения (без него будет http:// и вылазить предупреждение о том, что сайт не безопасен)

PS: для того чтобы залить новый билд требуется удалить все файлы в папке проекта и залить новые из билда(dist), иначе могут остаться старые файлы, которые будут мешать работе сайта