Публикация и обновление SmartApp

В этом разделе описано, как с помощью JavaScript на базе фреймворка React (можно использовать любой JavaScript фреймворк) в среде "eXpress" опубликовать SmartApp, а также как его обновить.

Термин	Определение
ивент	событие, которое передается от платформы чат-боту
сериализатор	cпрограмма, выполняющая процесс перевода структуры данных в последовательность байтов
asgi	клиент-серверный протокол взаимодействия веб-сервера и приложения
форматер	программа, выполняющая форматирование
линтер	программа для приведения кода к однообразию
front-end	клиентская сторона пользовательского интерфейса к программно-аппаратной части сервиса
uvicorn	сервер asgi

В работе будет использоваться следующее программное обеспечение:

• библиотека react;
• библиотека redux;
• библиотека redux-saga;
• библиотека reselect;
• язык программирования TypeScript;
• библиотека smartapp-bridge.

Библиотека smartapp-bridge (документация — https://smartapp.ccsteam.xyz/smartapp-bridge/) предоставляет универсальный интерфейс для обмена событиями с приложением "eXpress" и является обязательной (скачать библиотеку можно по ссылке https://github.com/ExpressApp/smartapp-bridge). Другое программное обеспечение из перечня можно заменить на аналогичное. Так же вам понадобиться любая среда разработки, в которой будет компилироваться приложение. По умолчанию предполагается, что среда "eXpress" уже развернута и успешно функционирует.

Публикация

Публикация влючает в себя следующие этапы:

• подготовка к работе;
• создание SmartApp;
• сборка приложения;
• подключение общего доступа.

Подготовка к работе

Подключение чат-бота к корпоративному серверу

1. В консоли администратора корпоративного сервера перейдите в пункт меню Боты.
2. В верхнем правом углу нажмите кнопку Создать бота.

3. Заполните поля настроек:

   

   Название поля	Информация
   Имя	Название чат-бота
   APP_ID	Уникальный текстовый идентификатор чат-бота
   URL	Ссылка на API чат-бота, при необходимости его можно заменить после окончания процесса разработки чат-бота
   Описание	Информация, дающая представление о предназначении чат-бота
   Статус сообщения	Сообщение, которое будет выводиться от имени администратора при обращении пользователя к чат-боту. Чат-бот должен быть отключен
   Версия протокола	Версия кода платформы BotX, используемая для отправки команды чат-боту
   Включено	Активирует/отключает чат-бота

4. Нажмите кнопку Сохранить.

У каждого чат-бота есть настраиваемые функции:

Название функции	Описание
allowed_data	Отвечает за типы сообщений, который принимает чат-бот. Возможные значения: all — чат-бот принимает все сообщения, отправленные в чат; commands — чат-бот принимает сообщение, если его упомянули в сообщении; none — чат-бот не принимает сообщений
communication_availability	Определяет типы пользователей, которым разрешен доступ к чат-боту. Возможные значения: all ─ доступ разрешен всем (RTS/CTS) пользователям; corporate ─ доступ разрешен корпоративным пользователям (значение по умолчанию); trust ─ доступ разрешен корпоративным пользователям локального CTS и пользователям c трастовых серверов; local ─ доступ разрешен пользователям локального CTS
show_in_catalog	Отображение в списке чат-ботов
allow_chat_creating	Создание чатов чат-ботом
use_botx_ca_cert	Использование чат-ботом сертификата SSL
use_pds_token	Электронная подпись документов с помощью сервиса ПДС
pds_key	Ключ ПДС

Чтобы настроить доступы чат-бота к сообщениям, в столбце "Имя" выберите чат-бота. Затем выполните следующие шаги:

1. Для активации функций allow_chat_creating и use_botx_ca_cert проставьте отметки в соответствующие поля.
2. Для подключения Smartapp установите флаг в соответствующем поле, введите имя чат-бота и выберите аватар из файловой системы.
3. Нажмите кнопку Сохранить.

Подготовка чат-бота

1. Скачайте репозиторий соответствующего бота.

   Скачанный проект состоит из следующих компонентов:

   app
   ‒ api	реализация конечных точек команд, на которые "eXpress" шлет события чат-боту для приложения, включая необходимые для чат-бота
   ‒ bot	определение обработчиков команд, вспомогательного кода и т.п. для чат-бота
   ‒ core	конфигурационные файлы, ивенты, общие для приложения сущности
   ‒ db	модели, функции для работы с БД и миграции
   ‒ resources	текстовые или файловые ресурсы бота
   ‒ schemas	сериализаторы
   ‒ services	сервисы с логикой работы чат-бота
   ‒ main.py	файл, в котором объявляется asgi приложение и регистрируются его компоненты
   scripts	скрипты для запуска тестов, форматеров, линтеров
   tests	тесты, структура которых соответствует структуре проекта
   pyproject.toml	конфигурация проекта с зависимостями, версией проекта и его авторами
   smartapp_files	сборка части front-end

   В проекте используются следующие переменные:

   • ref — уникальный идентификатор обращения;

   • data — перечень переменных, которые непосредственно используются при выполнении операций:

     • type — исполняющая команда;
     • query — переменная, над которой выполняется действие.

2. Установите зависимости проекта c помощью менеджера poetry:

   poetry install
   

3. Определите переменные окружения в файле с расширением .env. Пример рассмотрен в файле example.env.

4. При необходимости подготовьте новые команды с помощью библиотеки pybotx. Все команды чат-бота находятся в файле app.bot.commands и группируются в отдельные модули в зависимости от их логики. Весь текст выносится в файл resources.strings.

   Если необходимости в подготовке новых команд нет, перейдите к п.6.

5. Импортируйте их в файл app.bot.bot.

6. Запустите БД в фоне с использованием docker-compose:

   $ docker-compose up -d db
   

7. Накатите все миграции для инициализации БД с помощью программного обеспечения Alembic:

   $ alembic upgrade head
   

8. Запустите чат-бота как приложение FastAPI через сервер uvicorn.

   $ uvicorn app.main:app –reload
   

   

   Если в консоли появится сообщение, что приложение успешно запущено, то чат-бот работает. Пример успешного старта:

   

9. Загрузите чат-бот на сервер и повторите п. 1, 6-8.

Активация режима разработки в "eXpress"

Для активации режима разработки:

1. Откройте веб-приложение "eXpress".
2. Перейдите в пункт меню Настройки → О программе.

3. Выполните 10 щелчков левой кнопкой мыши по аватару сервера.

   Откроется окно:

   

4. Перейдите на вкладку "SmartApps".

   

5. Включите режим отладки, передвинув переключатель, и введите в оба поля ID чат-бота. ID чат-бота находится в его настройках в веб-интерфейсе администратора:

   

6. Нажмите кнопку Установить параметры отладки.

Создание SmartApp

Для создания SmartApp:

1. Скачайте репозиторий соответствующего бота.
2. Распакуйте скачанный архив.
3. В используемой среде разработки откройте распакованный архив.

4. Запустите установку пакетов:

   - npm i

5. Запустите процедуру разработки приложения:

   - npm start

   Запустите веб-приложение "eXpress" и начните чат с ботом, для которого разрабатывается SmartApp. В рабочей области появится окно с отлаживаемой SmartApp. Пользователи, не задействованные в разработке данной SmartApp, не будут иметь к ней доступа.

   

Сборка приложения

Для завершения процедуры разработки выполните следующие операции:

1. В используемой среде разработки выполните сборку приложения командой:

   npm run build
   

2. Перейдите в папку build и скопируйте ее в папку с файлами чат-бота. В рассматриваемом проекте папка build уже создана и называется smartapp_files. Замените содержимое папки smartapp_files на файлы, скомпилированные в папке build.

3. Загрузите чат-бот на сервер, повторите п. 1, 6-8 раздела "Подготовка чат-бота" и получите URL бота. URL бота укажите в настройках чат-бота на корпоративном сервере.

4. Откройте веб-приложение "eXpress".

5. Перейдите в пункт меню Настройки → О программе.
6. Выполните 10 щелчков левой кнопкой мыши по аватару сервера.

7. В открывшемся окне выберите вкладку "Experimental":

   

8. Передвиньте переключатель и закройте окно.

   В меню появится кнопка для работы со SmartApp

   

9. Нажмите кнопку .

   Появится окно, в котором перечислены все доступные к работе SmartApp:

   

10. Нажмите на иконку собранного приложения. Откроется окно, в котором производится дальнейшее взаимодействие со SmartApp.

Подключение общего доступа

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

1. Откройте пункт меню SmartApps.
2. Проставьте отметку в поле SmartApps включены.
3. Нажмите кнопку Сохранить

Обновление SmartApp

SmartApp является веб-приложением, поэтому для его обновления достаточно обновить контейнер, который будет содержать новую сборку. Клиент при загрузке SmartApp получит новые статические файлы.