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

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

Назначение документа

В данном документе описана общая функциональность мини-аппов в 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.

Для этого необходимо:

  1. Указать в переменных окружения QTвебENGINE_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
enable_testing=true

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

    open /Applications/VK/Teams.app

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

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

Уведомления от мини-аппа

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

Создание бота происходит через Метабота. Далее из кода мини-аппа вызываются методы Bot API отправки сообщений. Возможна отправка в бот любого контента, который доступен по Bot API.

По умолчанию все созданные боты не имеют прав писать сообщения первыми. Подобная опция проставляется администратором инсталляции для конкретного бота. В случае отсутствия такой опции пользователь не получит сообщение от бота, пока предварительно не запустит его вручную (команда /start).