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

Техническое описание мини-аппов

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

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

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

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

Регистрация мини-аппа — в документе описана регистрация мини-аппа при помощи Метабота VK Teams.

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

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

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

Общие сведения

Мини-апп является веб-приложением, которое открывается в VK Teams при помощи встроенного браузера:

  • В веб-версии для его отображения используется компонент Sandboxed iframe.
  • В десктоп- и мобильных приложениях — WebView.

Разработка мини-аппа

VK Teams не содержит инструментов для веб-разработки, поэтому предполагается самостоятельная разработка веб-приложений для интеграции.

Разработчик вправе использовать любые технологии веб-разработки.

Ниже в документации описаны некоторые особенности и ограничения работы мини-аппов в клиентских приложениях VK Teams, а также инструкции по регистрации мини-аппа, включая SDK для взаимодействия мини-аппа и клиентского приложения.

Обязательным условием для работоспособности мини-аппа в VK Teams является подключение библиотеки VK Teams Bridge для взаимодействия с клиентским приложением.

Выполнение запросов

Чтобы упростить аутентификацию и авторизацию клиента, а также чтобы обеспечить безопасность и повысить производительность, загрузка мини-аппа и выполнение Same Origin запросов к API происходит через сервер VK Teams. Взаимодействие сервера VK Teams и сервера мини-аппа осуществляется через интернет, только если сервер мини-аппа не размещен в локальной сети сервера VK Teams администратором кластера.

Для взаимной аутентификации сервера VK Teams и сервера мини-аппа используются SSL-сертификаты. При установлении SSL-соединения от сервера VK Teams к серверу мини-аппа сервер VK Teams проверяет, что полученная цепочка сертификатов ведет к корневому сертификату, указанному при создании (редактировании) мини-аппа. В свою очередь, сервер VK Teams также использует клиентский SSL-сертификат для предоставления серверу мини-аппа возможности удостовериться в подлинности источника запроса. Корневой клиентский сертификат VK Teams может быть получен от администратора кластера.

Схема загрузки и выполнения сетевых запросов мини-аппами представлена ниже:

Выполнение запросов к сторонним API

Также есть возможность выполнять API-запросы к сторонним API напрямую из клиента мини-аппа. Это делается путём добавления разрешённых хостов в настройки мини-аппа.

Для этого владелец мини-аппа должен перейти в Метабота и выполнить следующие шаги:

  1. Отправить боту команду /myapps.
  2. Выбрать мини-апп для настройки.
  3. Выбрать опцию «Set allowed cross-origin API hosts» и следовать инструкциям Метабота.

Авторизация в мини-аппе через сторонних провайдеров

При необходимости авторизации пользователя внутри мини-аппа методом OAuth2.0 следует воспользоваться PKCE-flow.

Инициализация процесса авторизации и возврат мини-аппу кода авторизации выполняется через библиотеку VK Teams Bridge при помощи запроса OpenAuthModal.

Интерфейс мини-аппа

В качестве UI-фреймворка для мини-аппа может быть использована любая дизайн-система.

Рекомендации к интерфейсу мини-аппа:

  1. Адаптивная вёрстка

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

  2. Переключение светлой и тёмной темы

    Клиентские приложения VK Teams имеют два режима оформления: светлый и тёмный, а также несколько цветовых тем. Мини-апп может получить данные о выбранной теме в клиентском приложении для того, чтобы сменить тему внутри мини-аппа. Например, применить светлый или тёмный режим. Для этого стоит использовать запрос GetThemeSettings и подписку ThemeSettings, которые оповещают Web-приложение о выбранной в приложении теме оформления.

Хранение информации мини-аппа

Из соображений безопасности, а также в связи с техническими ограничениями некоторых платформ (веб) в части удаления cookie-файлов при завершении сессии пользователя cookie-файлы сохраняться не будут.

Мини-апп может сохранять данные в формате ключ-значение на устройстве пользователя при помощи библиотеки VK Teams Bridge, используя запросы StoragePut, StorageGet, StorageClear, StorageDelete.

Персистентное хранилище мини-аппа расположено в клиентском приложении для всех операционных систем и имеет ограничение на максимальный размер для одного мини-аппа 10 МБ. Уровень защищённости данных в хранилище такой же, как для всех данных приложения VK Teams. В персистентном хранилище также можно хранить и файлы, если позволяет ограничение по размеру хранилища.

Хранилище мини-аппа очищается, если пользователь вышел из своего аккаунта.

Отладка мини-аппа в VK Teams

Для отладки мини-аппа внутри клиентского приложения VK Teams можно использовать Chrome DevTools. Это можно сделать в десктоп-приложении VK Teams (Windows, macOS, Linux).

Для этого :

  1. Укажите в переменных окружения QTWEBENGINE_CHROMIUM_FLAGS=--remote-debugging-port=NNN, где NNN — номер порта.

  2. Откройте конфигурационный файл app.ini, который находится в папке с установленным приложением:

    Для macOS: ~/Library/Application Support/VK Teams/app.ini

    Для ОС Windows: c:\Users%USERNAME%\AppData\Roaming\VK Teams\:

    Для ОС Linux: /home/%user%/.config/VK Teams

    и внесите туда изменения: 

    dev_id=1

  3. Запустите приложение через терминал: 

    open /Applications/VK/Teams.app

    Шапка приложения должна стать оранжевой.

  4. Перейдите по адресу http://127.0.0.1:NNN в браузере на базе chromium (например, Google Chrome). После этого станет доступна отладка.

Поддержка обновлений мини-аппа в запущенном клиентском приложении

После интеграции мини-аппа, может возникнуть необходимость обновления клиентского кода (исполняемого внутри webview-компоненты). Для того, чтобы иметь возможность обновлять код, серверу мини-аппа необходимо поддерживать выдачу заголовка Last Modified .

Если при повторном входе в мини-апп сервер миниаппа отдаёт новое значение Last Modified, код мини-аппа будет обновлён на клиенте.

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

Другие ограничения и особенности

  1. Same Origin запросы должны выполняться неявно (без имени хоста)

    Мини-апп может выполнять только Same Origin запросы, при этом хост не должен указываться в запросе явно, так как мини-апп может быть загружен с произвольного хоста в поддоменах VK Teams.

  2. Window.history недоступен для навигации

    Мини-апп не должен менять window.history. Для навигации по разделам мини-аппа следует воспользоваться библиотеками, поддерживающими хранение истории в памяти приложения, например, React Memory Router.

  3. Cookie-файлы

    Сервер мини-аппа не должен выставлять cookie-файлы в ответ на запрос на загрузку веб-приложения и последующие Same Origin запросы. Из соображений безопасности, а также в связи с техническими ограничениями некоторых платформ (веб) в части удаления cookie-файлов при завершении сессии пользователя, cookie-файлы сохраняться не будут.

    Для хранения информации рекомендуем использовать хранилище мини-аппа на стороне клиента. Управление хранилищем происходит через библиотеку VK Teams Bridge, используя запросы StoragePut, StorageGet, StorageClear, StorageDelete.