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

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

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

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

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

PWA (React)(1).png

Приложение будет передавать введённые пользователем данные в 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» и создать активную конечную точку. Например алиас wright,user_events, метод POST, формат JSON.

        image.png

        Этот обработчик получает calculator, table и data, убирает начальный $ у ключей данных, проверяет таблицу по разрешённому спискуdata и создаёт запись:

        varlet createditem = table.createItem(tableName,"user_events", data){
  session_id: data.session_id,
  event_type: data.event_type
});

        Для новой таблицы нужно добавить её техническое имя в allowedTables. Например, bmi уже есть в списке на скриншоте. Параметр calculator в этом обработчике проверяется на наличие, но отдельно в таблицу не записывается.

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

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

        { 
  "script_request_params": { 
      "calculator": "bmi", 
      "table": "bmi", 
      "data": { 
        "user_id"session_id": "123", 
        "result"event_type": 24.5 
      } 
  } 
}

        user_id и result здесь — примеры: заменить их полями своей таблицы. Обёртка script_request_params нужна для доступа к этим данным через request.json в обработчике Метабот.

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

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

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

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

        1. Проверка API

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

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

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

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

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

        Затем3. проверитьПроверка отправкуPWA

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

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

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

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

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

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

        Важно: запросы из приложения.Swagger Показыватьи сообщение об успешном сохранении после подтверждения записи, а при ошибке — предлагать повторить отправку. Запросы в SwaggerPostman создают реальные записи.записи в таблицах. Для проверки используйте тестовые данные.

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

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

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

        npm run build

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

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

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

          Исходный проект необходим для внесения изменений и повторной сборки.

          Папка dist предназначена для публикации уже собранного приложения.

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

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

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

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