Общая информация о мини-аппах
Назначение документа
В данном документе описана общая функциональность мини-аппов в VK Teams.
Документ предназначен для использования конечными пользователями и администраторами организации.
Дополнительная документация
Создание мини-аппа — в документе описано создание мини-аппа в VK Teams с использованием библиотеки VK Teams Bridge.
Библиотека VK Teams Bridge — в документе описаны методы взаимодействия мини-аппа с нативным клиентом VK Teams.
Архитектура и описание системы — в документе представлена информация о сервисах VK Teams, обеспечивающих функциональность мини-аппов. Не является частью публичной документации, обратитесь к представителю VK Tech, чтобы ознакомиться с документом.
Что такое мини-аппы в VK Teams
Мини-аппы в VK Teams — это платформа для встраивания веб-приложений в VK Teams для использования их непосредственно из супер-аппа. Таким образом расширяется функциональность продукта за счет интеграций:
-
Сервисы объединяются в одном приложении — минимизация переключения контекста.
-
Кроссплатформенность — мини-аппы доступны сразу на всех платформах, где работает супер-апп.
-
Моментальная дистрибуция сервисов через одно приложение — быстрое обновление.
При добавлении в VK Teams веб-сервисов в качестве мини-аппов у пользователя появляется удобный доступ к корпоративным сервисам, которыми он пользуется на регулярной основе.
Примеры мини-аппов — сервисы личного кабинета сотрудника:
-
Работа с отпусками.
-
Получение расчетного листка.
-
Корпоративные блоги.
-
Новостные разделы и корпоративные социальные сети.
Также мини-аппом может быть страница с набором полезных ссылок команды или компании.
Мини-апп открывается в VK Teams на все рабочее пространство с возможностью возврата назад.
Открыть мини-апп VK Teams можно из мессенджера, отправив ссылку на мини-апп. У любого мини-аппа VK Teams есть ссылка, с которой можно работать. При оправке ссылки на мини-апп в VK Teams мини-апп также откроется на все рабочее пространство с возможностью возврата назад в чат.
Техническое описание мини-аппов
Общие сведения
Мини-апп в VK Teams является одностраничным веб-приложением.
В нативных клиентах для Windows, macOS, Linux, iOS и Android приложение VK Teams выступает в качестве браузера по отношению к мини-аппам. Для их отображения используется компонент вебView.
В веб-версии VK Teams для отображения мини-аппов используется Sandboxed iframe.
Выполнение запросов минни-аппами
Чтобы упростить аутентификацию и авторизацию клиента, а также для обеспечить безопасность и повысить производительность, загрузка мини-аппа и выполнение same-origin запросов к API происходит через сервер VK Teams.
Взаимодействие сервера VK Teams и сервера мини-аппа осуществляется через интернет, только если сервер мини-аппа не размещен в локальной сети сервера VK Teams администратором кластера.
Для взаимной аутентификации сервера VK Teams и сервера мини-аппа используются SSL-сертификаты. При установлении SSL-соединения от сервера VK Teams к серверу мини-аппа сервер VK Teams проверяет, что полученная цепочка сертификатов ведет к корневому сертификату, указанному при создании (редактировании) мини-аппа. В свою очередь, сервер VK Teams также использует клиентский SSL-сертификат для предоставления серверу мини-аппа возможности удостовериться в подлинности источника запроса. Корневой клиентский сертификат VK Teams может быть получен от администратора кластера.
Схема загрузки и выполнения сетевых запросов мини-аппами представлена ниже:
Существует возможность выполнять API-запросы к сторонним API напрямую из клиента мини-аппа, но список таких адресов должен быть заранее задан путем настройки мини-аппа (или при его создании).
Авторизация в мини-апп через сторонние провайдеры
При необходимости авторизации пользователя внутри мини-аппа методом OAuth2.0 следует воспользоваться PKCE-flow.
Инициализация процесса авторизации и возврат мини-аппу Authorization Code выполняются через библиотеку VK Teams Bridge.
Сохранение состояния мини-аппа между перезапусками
Мини-апп может сохранять данные в формате ключ-значение на устройстве пользователя при помощи библиотеки VK Teams Bridge (см. Библиотека VK Teams Bridge).
Все сохраненные мини-аппом данные будут очищены при выходе пользователя из аккаунта.
Создание мини-аппа
В настоящий момент VK Teams не содержит инструментов для разработки веб-приложений. VK Teams предоставляет возможность зарегистрировать и подключить предварительно созданные веб-приложения. Таким образом перед интеграцией мини-аппа в VK Teams его необходимо предварительно создать. Разрабатывать мини-апп можно любыми доступными веб-средствами.
В инструкции Создание мини-аппа описано создание мини-аппа в VK Teams с использованием библиотеки VK Teams Bridge.
Требования и ограничения
При разработке мини-аппа для VK Teams накладываются следующие требования и ограничения:
-
Same-origin запросы должны выполняться неявно (без имени хоста). Мини-апп может выполнять только same-origin запросы, при этом хост не должен указываться в запросе явно, так как мини-апп может быть загружен с произвольного хоста в поддоменах VK Teams.
-
Для cross-origin запросов необходимо заранее указать домен ресурса в CSP заголовках на стороне VK Teams.
-
Window.history недоступен для навигации. Мини-апп не должен менять window.history. Для навигации по разделам мини-аппа следует воспользоваться библиотеками, поддерживающими хранение истории в памяти приложения, например React Memory Router.
-
Вместо localStorage локальные данные необходимо хранить на клиенте через Bridge API.
-
Использование cookie запрещено. Сервер мини-аппа не должен выставлять cookie в ответ на запрос на загрузку SPA и последующие same-origin запросы. Из соображений безопасности, а также в связи с техническими ограничениями некоторых платформ (веб) в части удаления cookie при завершении сессии пользователя, cookie сохраняться не будут. Для хранения информации в хранилище на стороне клиента необходимо пользоваться соответствующим методом JS SDK.
-
Поскольку мини-апп доступен пользователю VK Teams на всех платформах, его верстка должна быть адаптивной для экранов с минимальной шириной 380px.
Просмотр списка своих мини-аппов
Вы можете посмотреть список своих мини-аппов в Метаботе. Для этого отправьте боту команду /myapps.
Ссылка на мини-апп
Переход в мини-апп VK Teams возможен по ссылке на мини-апп. Такая ссылка может использоваться в мессенджере, в любых других мини-аппах, а также в браузере.
При открытии ссылки из браузера происходит редирект в установленное приложение на соответствующий раздел (мини-апп). К открываемой начальной странице мини-аппа будут добавлены query-параметры и fragment из ссылки. Это дает возможность открывать мини-апп на произвольной странице и организовывать глубокие интеграции между разными мини-аппами и ботами.
Для создания ссылки как на текущий мини-апп, так и на другой, из кода мини-аппа можно воспользоваться библиотекой VK Teams Bridge GetMiniAppShareLink. Для создания ссылок на мини-аппы на стороне сервера следует уточнить формат ссылок у администратора кластера VK Teams.
Формат ссылки:
https://[base_url]/miniapp/[miniapp_id]
Пример ссылки на мини-апп:
https://u.internal.myteam.mail.ru/miniapp/miniapp-16c6c83e-075f-4d92-b840-ad1991f3445c
Отладка мини-аппа в VK Teams
После интеграции мини-аппа в VK Teams может возникнуть необходимость его отладки внутри приложения. Это можно сделать в VK Teams Desktop (Windows, macOS, Linux).
Так как приложение основано на chromium, для отладки можно использовать Chrome DevTools.
Для этого необходимо:
-
Указать в переменных окружения QTвебENGINE_CHROMIUM_FLAGS=--remote-debugging-port=NNN, где NNN — номер порта.
-
Открыть конфигурационный файл app.ini, который находится в папке с установленным приложением:
Для macOS: ~/Library/Application Support/VK Teams/app.ini
Для ОС Windows: c:\Users%USERNAME%\AppData\Roaming\VK Teams\:
Для ОС Linux: /home/%user%/.config/VK Teams
и внести туда изменения:
-
Запустить приложение через терминал:
Шапка приложения должна стать оранжевой.
-
Открыть адрес http://127.0.0.1:NNN в браузере на базе chromium (например, Google Chrome). После этого станет доступна отладка.
Уведомления от мини-аппа
Для рассылки уведомлений от мини-аппа можно использовать ботов VK Teams. Особых требований к боту для использования в мини-аппах нет.
Создание бота происходит через Метабота. Далее из кода мини-аппа вызываются методы Bot API отправки сообщений. Возможна отправка в бот любого контента, который доступен по Bot API.
По умолчанию все созданные боты не имеют прав писать сообщения первыми. Подобная опция проставляется администратором инсталляции для конкретного бота. В случае отсутствия такой опции пользователь не получит сообщение от бота, пока предварительно не запустит его вручную (команда /start).