Перейти к содержанию

Регистрация мини-аппа

Дополнительная документация

Общая информация — в документе описано, что такое мини-аппы, и как они выглядят в клиентском приложении.

Техническое описание — в документе описаны принципы разработки мини-аппа, выполнение запросов, авторизация и отладка мини-аппа.

Создание мини-аппа — в документе описано создание мини-аппа в VK WorkSpace с использованием библиотеки VK Teams Bridge.

Библиотека VK Teams Bridge — в документе описаны методы взаимодействия мини-аппа с нативным клиентом VK WorkSpace.

Публикация мини-аппа в панель сервисов Супераппа VK WorkSpace — в документе описаны способы публикации мини-аппа для отображения в в панели сервисов VK WorkSpace.

FAQ — в разделе собраны часты вопросы при работе с мини-аппами.

Архитектура и описание системы — в документе представлена информация о сервисах Супераппа, обеспечивающих функциональность мини-аппов. Не является частью публичной документации, обратитесь к представителю VK Tech, чтобы ознакомиться с документом.

Общая информация

Для открытия веб-приложения в качестве мини-аппа в VK WorkSpace, мини-апп нужно зарегистрировать.

После регистрации пользователи могу использовать мини-аппа двумя способами:

  1. Мини-апп публикуется в навигационную панель приложения и доступен всем пользователям при клике на иконку.
  2. Мини-апп не публикуется для всех пользователей и доступен для использования по ссылке — тем, у кого есть ссылка на мини-апп.

Шаг 1. Создайте веб-приложение

В инструкции Создание мини-аппа в качестве примера описано создание мини-аппа в VK WorkSpace с использованием библиотеки VK Teams Bridge.

Шаг 2. Подключите библиотеку VK Teams Bridge

Обязательным условием для открытия мини-аппа в VK WorkSpace является получение от мини-аппа сигнала LoadingCompleted из библиотеки VK Teams Bridge с параметром ok:true. Запрос LoadingCompleted отправляется с фронта мини-аппа с целью оповещения приложения об успешной загрузке JS для защиты пользователя от ошибок встроенного браузера. В случае если приложение не получило сигнал в течение 8 секунд, пользователь увидит сообщение «Не удалось загрузить».

Инструкцию по подключению библиотеки и отправки запросов можно найти в разделе Библиотека VK Teams Bridge.

Шаг 3. Подготовьте артефакты, необходимые для регистрации мини-аппа.

Для регистрации мини-аппа в VK WorkSpace вам понадобится:

  1. Название мини-аппа.

  2. Описание мини-аппа.

  3. Картинка в формате PNG.

    Требования к картинке:
    - разрешение не мене 1024х1024px.
    - квадрат.
    Скачать пример картинки

  4. Иконка в формате SVG для невыбранного таба.

    Требования:
    - монохромная;
    - без встроенных стилей и скриптов.

    Скачать пример иконки

  5. Иконка в формате SVG для выбранного таба.

    Требования:
    - монохромная;
    - без встроенных стилей и скриптов.

    Скачать пример иконки

Также вам понадобится:

  1. Самоподписанный SSL-сертификат, используемый для аутентификации сервера мини-аппа сервером VK WorkSpace. Процесс генерации описан в шаге 4.

  2. URL-адрес сервера мини-аппа. Допустимые части URL-адреса:

    • schema (обязательно HTTPS) — обязательно;
    • host — обязательно;
    • port;
    • path.

URL-адрес сервера мини-аппа, а также его сертификат необязательны на этапе регистрации, однако обязательны для успешного открытия мини-аппа в приложении.

Шаг 4. Сгенерируйте самоподписанный сертификат

Взаимодействие между сервером VK WorkSpace и веб-сервером мини-аппа осуществляется по mTLS. Поэтому веб-сервер мини-аппа должен использовать самоподписанный сертификат с соответствующим CN, который будет указываться при регистрации мини-аппа в приложении.

Для генерации сертификата должен быть установлен OpenSSL. Чтобы проверить установлен ли он, выполните в терминале команду openssl -v. Если OpenSSL не установлен, установите его.

Сгенерируйте сертификат командой:

openssl req -x509 -days 36500 -subj "/CN=HOST DOMAIN NAME" -newkey rsa:4096 -nodes -keyout key.pem -out crt.pem

где CN — префикс + зарегистрированный домен.

В результате выполнения команды в директории должны появиться файлы key.pem и crt.pem. Данные файлы необходимы для запуска веб-сервера мини-аппа. Файл crt.pem будет использоваться при регистрации мини-аппа в Метаботе на шаге 5.

Шаг 5. Зарегистрируйте мини-аппа в Метаботе

  1. Перейдите в клиентское приложение VK WorkSpace и найдите Метабот.

  2. Отправьте боту команду /newapp и следуйте инструкциям бота.

    При успешном завершении регистрации Метабот отправляет сообщение со ссылкой на мини-апп, которой можно пользоваться и пересылать коллегам. Ссылка на мини-апп содержит базовую часть, а также ID нового мини-аппа. Пример ссылки на мини-апп: https://u.internal.myteam.mail.ru/miniapp/miniapp-16c6c83e-075f-4d92-b840-ad1991f3445c.

  3. Добавьте URL-адрес на ваш домен и сгенерированный сертификат crt.pem. Нажмите на Set backend URL and certificate и отправьте боту эти данные. При необходимости укажите относительный путь и список разрешённых хостов для внешних API-запросов.

Если все прошло успешно, бот выводит сообщение «The mini app backend info is updated». При нажатии на ссылку мини-аппа, он отображается в приложении.

Управление мини-аппами

Управление своими мини-аппами происходит из Метабота при помощи команды /myapps. Команда выводит список мини-аппов, где пользователь является создателем, и позволяет редактировать их атрибуты.