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

Мини-аппы в VK Teams

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

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

Документ предназначен для использования конечными пользователями и администраторами организации.

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

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

Что такое мини-аппы в VK Teams

Мини-аппы в VK Teams — это платформа для встраивания WEB-приложений в VK Teams для использования их непосредственно из супер-аппа, тем самым расширяется функциональность продукта за счёт интеграций.

Сервисы объединяются в одном приложении:

  • минимизация переключения контекста;

Кроссплатформенность:

  • мини-аппы доступны сразу на всех платформах, где работает супер-апп;

Моментальная дистрибуция сервисов через одно приложение:

  • быстрое обновление.

При добавлении в VK Teams WEB-сервисов в качестве мини-аппов у пользователя появляется удобный доступ к корпоративным сервисам, используемым на регулярной основе.

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

  • работа с отпусками;

  • получение расчётного листка;

  • корпоративные блоги;

  • новостные разделы и корпоративные социальные сети.

Также мини-аппом может быть страница с набором полезных ссылок команды или компании.

Мини-апп открывается в VK Teams на всё рабочее пространство с возможностью возврата назад.

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

У любого мини-аппа VK Teams есть ссылка, с которой можно работать. При оправке ссылки на мини-апп в VK Teams мини-апп также откроется на всё рабочее пространство с возможностью возврата назад в чат.

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

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

Мини-апп в VK Teams является одностраничным Web-приложением.

В нативных клиентах (VK Teams для Windows, macOS, Linux, iOS и Android) приложение VK Teams выступает в качестве браузера по отношению к мини-аппам. Для их отображения используется компонент WebView.

В Web-версии 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 не содержит инструментов для разработки WEB-приложений. VK Teams предоставляет возможность зарегистрировать и подключить предварительно созданные WEB-приложения. Таким образом перед интеграцией мини-аппа в VK Teams его необходимо предварительно создать и сгенерировать SSL-сертификат. Процесс создания SSL_сертификата представлен в разделе Генерация SSL-сертификата.

В разделе Требования и ограничения описаны требования и ограничения, которые необходимо соблюдать при разработке мини-аппа.

Разрабатывать мини-апп можно любыми доступными WEB-средствами. В разделе Дизайн мини-аппа описаны средства, которые можно использовать при создании мини-аппа для оформления его в теме нативного клиента.

Требования и ограничения

При разработке мини-аппа для VK Teams накладываются следующие требования и ограничения:

  • Same-origin запросы должны выполняться неявно (без имени хоста);

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

  • Вместо localStorage, локальные данные необходимо хранить на клиенте через Bridge API;

  • Использование cookie запрещено (бэкенд мини-аппа не должен ставить cookie);

  • Для cross-origin запросов необходимо заранее указать домен ресурса в CSP заголовках на стороне VK Teams.

Адаптивность

Поскольку мини-апп доступен пользователю VK Teams на всех платформах, его вёрстка должна быть адаптивной для экранов с минимальной шириной 380px.

Запросы

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

Навигация по мини-аппу

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

Cookies

Сервер мини-аппа не должен выставлять Cookie в ответ на запрос на загрузку SPA и последующие Same-origin запросы.

Из соображений безопасности, а также в связи с техническими ограничениями некоторых платформ (Web) в части удаления Cookie при завершении сессии пользователя, Cookie сохраняться не будут. Для хранения информации в хранилище на стороне клиента необходимо пользоваться соответствующим методом JS SDK.

Генерация SSL-сертификата

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

  1. Сгенерируйте SSL-сертификат.

    Пример команды для генерации сертификата:

    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 используется при регистрации мини-аппа в Метаботе.

  2. На сервере миниаппа в конфигурации nginx добавьте поле:

    ssl_client_certificate file;
    

    , где file — это путь к приватному ключу SSL-сертификата.

    Пример:

    ssl_client_certificate /ca/ca.crt;
    

Дизайн мини-аппа

Вёрстка мини-аппа является адаптивной как для Desktop / Web, так и для мобильных платформ.

Для оформления Mini App SPA в консистентном с клиентом VK Teams виде предусмотрен метод GetThemeSettings для получения мини-аппом темы клиента, а также нотификации об её изменении.

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

Библиотека VKUI

VKUI — это библиотека адаптивных React-компонентов, с помощью которой можно создавать Web-приложения.

Библиотека основана на дизайн-системе ВКонтакте и реализует её интерфейсы для различных платформ.

Преимущества VKUI:

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

- Разные цветовые схемы. Тёмная тема — один из самых важных факторов доступности.

Использование VKUI для проектирования мини-аппов

https://www.figma.com/@vk

Подключение библиотек

Система цветов

Типографика

Использование компонентов

Кастомные компоненты

Темная тема

Растягивание элементов

Интеграция мини-аппа в VK Teams

После подготовки WEB-сервиса к использованию можно приступать к интеграции в VK Teams.

Чтобы работать с мини-аппом в VK Teams, его нужно зарегистрировать. Зарегистрировать мини-апп может любой пользователь.

Регистрация мини-аппа в VK Teams осуществляется при помощи бота VK Teams @metabot (см. раздел Регистрация мини-аппа при помощи Метабота).

Примечание

При регистрации мини-аппа при помощи Метабота не происходит создания иконки мини-аппа в левой навигационной панели Сервисов в VK Teams.

Регистрация мини-аппа при помощи Метабота

Зарегистрировать мини-апп в VK Teams можно из бота @metabot, с помощью которого можно создать как бот, так и мини-апп. Зарегистрировать мини-апп может любой сотрудник, так как доступ к Метаботу есть у всех.

Процедура регистрации требует:

  1. Чтобы сервер мини-аппа был доступен по сети с сервера мессенджера;
  2. Чтобы сервер мини-апп использовал самоподписанный сертификат с таким же CN, как тот, что будет указан в качестве backend-url при регистрации мини-аппа в Метаботе;
  3. Атрибуты мини-аппа должны удовлетворять требованиям (см. раздел Атрибуты, необходимые для регистрации мини-аппа);

Перейдите в Метабота — для этого можно использовать ссылку, или найти бота вручную, набрав в поиске VK Teams Metabot.

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

Атрибуты, необходимые для регистрации мини-аппа

Для регистрации мини-аппа необходимы следующие атрибуты:

Атрибут Описание
1. Название мини-аппа Название, которое будет отображаться в заголовке мини-аппа, а также в разделе Сервисы VK Teams, если мини-апп будет в дальнейшем опубликован в Сервисах для всех сотрудников.
2. Описание мини-аппа Описание сервиса, которое будет отображаться в разделе Сервисы VK Teams, если мини-апп будет в дальнейшем опубликован в Сервисы для всех сотрудников.
3. Картинка PNG Логотип мини-аппа в формате PNG, который будет отображаться в разделе Сервисы VK Teams, если мини-апп будет в дальнейшем опубликован в Сервисы для всех сотрудников.
Требования к PNG:
- разрешение не мене 1024х1024px
- квадрат.
4. Иконка SVG для невыбранного ''таба" Иконка в формате SVG, которая будет отображаться на левой панели VK Teams Windows, macOS, Linux и Web, если мини-апп будет в дальнейшем опубликован в Сервисы для всех сотрудников. Данная иконка соответствует состоянию, когда мини-апп не выбран.
Требования:
- монохромная;
- без встроенных стилей и скриптов.
Иконка SVG для «выбранного таба»>
5. Иконка SVG для ''выбранного таба" Иконка в формате SVG, которая будет отображаться на левой панели VK Teams Windows, macOS, Linux и Web, если мини-апп будет в дальнейшем опубликован в Сервисы для всех сотрудников. Данная иконка соответствует состоянию, когда мини-апп выбран.
Требования:
- монохромная;
- без встроенных стилей и скриптов.
Иконка SVG для «выбранного таба»
6. URL сервера мини-аппа Базовый URL сервера мини-аппа, на базе которого будут формироваться URL'ы для отправки запросов.
Допустимые части URL'a:
- schema (обязательно https); required
- host; required
- port;
- path.
Если мини-апп необходимо открывать с определённой начальной страницы, то относительный путь можно будет задать на другом шаге.
7. Сертификат сервера мини-аппа Самоподписанный SSL-сертификат, используемый для аутентификации сервера мини-аппа сервером VK Teams.

При успешном завершении регистрации мини-аппа Метабот отправляет сообщение со ссылкой на мини-апп, которой можно пользоваться и пересылать коллегам.

Ссылка на мини-апп содержит базовую часть, а также ID нового мини-аппа.

Пример ссылки на мини-апп:

https://u.internal.myteam.mail.ru/miniapp/miniapp-16c6c83e-075f-4d92-b840-ad1991f3445c

Публикация мини-аппа при помощи API мини-аппов

Опубликовать мини-апп можно при помощи выполнения запросов API мини-аппов.

Предусловия для взаимодействия с API мини-аппа:

  • необходим доступ в окружение администратора — интерфейс администратора доступен только пользователям, добавленным в группу с доступом в окружение администратора (управление пользователями представлено в документе «Руководство по администрированию»);
  • необходима авторизация в окружении администратора.

Ниже представлены запросы для публикации мини-аппа:

Шаг 1. Сгенерировать OTP:

curl 'https://admin.<DOMAIN>/auth/otp/generate' \
-H 'Content-Type: application/json' \
-d '{"email": "user@mail.ru"}'

, где:

  • <DOMAIN> — А-запись (домен инсталляции VK Teams);
  • user@mail.ru — пользователь с доступом в окружение администратора.

Шаг 2. Проверить OTP:

curl 'https://admin.<DOMAIN>/auth/otp/check' \
-H 'Content-Type: application/json' \
-d '{"email": "user@mail.ru", "password": "OTP"}' \
-c cookiefile.txt

, где:

  • <DOMAIN> — А-запись (домен инсталляции VK Teams);
  • user@mail.ru — пользователь с доступом в окружение администратора;
  • password — OTP, сгенерированный на шаге 1, приходит на почту пользователя с доступом в окружение администратора.

Шаг 3. Посмотреть зарегистрированные мини-аппы:

curl 'https://admin.<DOMAIN>/api/miniapp/list' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-b cookiefile.txt \
-d ''

, где:

  • <DOMAIN> — А-запись (домен инсталляции VK Teams).

Шаг 4. Опубликовать мини-апп:

curl 'https://admin.<DOMAIN>/api/miniapp/enable' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-b cookiefile.txt \
-d '{"miniappId":"miniapp-04c4ec24-2237-4a8f-934e-4ad1ef07f45f"}'

, где:

  • <DOMAIN> — А-запись (домен инсталляции VK Teams);
  • miniappId — идентификатор мини-аппа, который необходимо опубликовать. Идентификатор мини-аппа можно получить из бота @metabot при помощи запроса /myapps, который выводит список созданных мини-аппов.

Просмотр списка своих мини-аппов

В Метаботе есть возможность посмотреть список всех своих мини-аппов для их настройки. Для этого необходимо открыть Метабота и отправить ему команду /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. Указать в переменных окружения QTWEBENGINE_CHROMIUM_FLAGS=--remote-debugging-port=NNN, где NNN номер порта.
  2. Открыть конфигурационный файл app.ini, который находится в папке с установленным приложением (~/Library/Application Support/VK Teams/app.ini), и внести туда изменения:

    • dev_id=1
    • enable_testing=true
  3. Запустить приложение через терминал:

    • open /Applications/VK/Teams.app
    • шапка приложения должна стать оранжевой.
  4. Открыть адрес http://127.0.0.1:NNN в браузере на базе chromium (например, Google Chrome), после чего станет доступна отладка.

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

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

Создание бота происходит через Метабота @metabot.

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

По умолчанию все созданные боты не имеют прав писать сообщения первыми. Подобная опция проставляется администратором инсталляции для конкретного бота.

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

Библиотека VK Teams Bridge

Взаимодействие мини-аппа с нативным клиентом VK Teams осуществляется через библиотеку VK Teams Bridge. Она отвечает за предоставление JavaScript-коду мини-аппа удобного интерфейса для вызова функций нативного клиента.

Библиотека позволяет обращаться к нативному клиенту за различными данными или действиями для плотной интеграции с продуктом.

Код библиотеки абстрагирован от протокола JS SDK и осуществляет лишь передачу запроса-ответа между мини-аппом и нативным приложением.

Отправка запросов в основное приложение (метод send)

Аргументы функции:

  • Название запроса (string);

  • Параметры запроса (object). //в случае, если у запроса нет параметров — null

Результат в случае успешной обработки — поля ответа (object). //в случае, если полей ответа нет — пустой объект

Результат в случае ошибки — объект с полями:

  • code (string); //содержит код ошибки

  • reason (string). //содержит описание ошибки

Общий формат вызова метода

bridge.send(
  <название запроса>, // string
  {
    <параметры запроса>
  }
).then(({
  <параметры ответа>
}) => {
  <обработка ответа>
}).catch(({
  code,   // string
  reason, // string
}) => {
  <обработка ошибки>
})

Общие коды ошибок

  • BAD_REQUEST;

  • NETWORK_ERROR;

  • INTERNAL_ERROR.

Перечень и описание запросов

CreateChat

Открыть модальное окно/раздел создания группового чата.

Поведение клиентов:

Desktop и Web:

  • Поверх мини-аппа открывается модальное окно создания группы;
  • При отмене создания модалка закрывается;
  • При успешном создании группового чата:
  • Происходит переход во вкладку Чаты.
  • Открывается созданный групповой чат;
  • В заголовке чата появляется стрелка Назад для возврата в мини-апп.

Mobile:

  • Поверх мини-аппа открывается раздел создания группы;
  • При возврате назад, происходит возврат в мини-апп;
  • При успешном создании группового чата:
  • Открывается созданный групповой чат.
  • При возврате Назад, пользователь попадает
    • в список чатов на iOS;
    • обратно в мини-апп на Android.
Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
name string Название чата chatId
string Идентификатор
созданного чата
(например,
123@chat.agent)
BAD_REQUEST Не выполнены ограничения
на длину названия
(по умолчанию не более
255 символов) или
количество участников чата
(по умолчанию не более
25000).
members string Список участников чата. Содержит уникальные идентификаторы (sn/email) пользователей внутри сервиса. Если в списке содержатся внешние участники (участники не имеющие идентификатора внутри сервиса), то
"клиент" отображает диалоговое
окно, что данные участники не
будут добавлены в групповой чат.
Для проверки принадлежности
участников сервису клиент
использует "контакт-лист"
текущего пользователя.
Если участник отсутствует
в "контакт-листе" пользователя,
то принадлежность проверяется
при помощи запроса API
/rapi/getIdInfoBatch
url string Ссылка на чат MODAL_CLOSED Модальное окно было закрыто
CREATE_FAILED Ошибка создания чата. Чат не был создан из-за ошибок на стороне "клиента", либо из-за внутренних ошибок на стороне сервера

LoadingCompleted

Позволяет проинформировать клиентское приложение об успешном завершении загрузки мини-аппа.

Примечание

Вызов данного метода является необходимым условием для успешного открытия мини-аппа в VK Teams.

При открытии мини-аппа в VK Teams, необходимо информирование клиента о том, что мини-апп был успешно загружен. Иначе есть риск загрузить неработающую страницу без возможности обновить или вернуться назад.

При передаче значения ok:true мини-апп успешно открывается.

При передаче значения ok:false, либо, если запрос LoadingCompleted не получен клиентским приложением в течение 10 секунд после открытия мини-аппа, VK Teams отображает заглушку с кнопкой Повторить попытку:

Кнопка **Повторить попытку**

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
ok
*required
boolean ALREADY_
CALLED
Запрос выполнен дважды

OpenProfile

Позволяет открыть профиль пользователя, бота или группового чата из мини-аппа. При вызове данного метода произойдёт переход в профиль чата в VK Teams с заданным ID с возможностью возврата назад в мини-апп.

Если в качестве ID задан несуществующий объект, то возвращается ошибка с кодом PROFILE_NOT_FOUND.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
chatId
*required
string PROFILE_NOT_
FOUND
Профиль не найден

OpenDialog

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

Также есть возможность открытия чата на позиции конкретного сообщения при наличии ID этого сообщения.

Если в качестве ID задан несуществующий объект, то возвращается ошибка с кодом DIALOG_NOT_FOUND.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
chatId
*required
string DIALOG_NOT_FOUND Диалог не найден
messageId
*required
string ID сообщения, на котором необходимо сфокусироваться. При отсутствии параметра, чат открывается на первом непрочитанном сообщении.

OpenThread

Позволяет открыть обсуждение (тред) конкретного сообщения. При вызове данного метода происходит переход в чат VK Teams, и в чате открывается обсуждение с заданным ID.

Также есть возможность открытия обсуждения на позиции конкретного сообщения при наличии ID этого сообщения.

Если в качестве ID задан несуществующий объект, то возвращается ошибка с кодом DIALOG_NOT_FOUND.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
threadId
*required
string DIALOG_NOT_FOUND Диалог не найден
messageId
*required
string ID сообщения, на котором необходимо сфокусироваться. При отсутствии параметра, чат открывается на первом непрочитанном сообщении.

SetTitle

Позволяет изменить заголовок мини-аппа в любом из разделов внутри него.

Заголовок (header) мини-аппа является нативным на стороне VK Teams. По умолчанию, заголовком мини-аппа является его название, обозначенное при интеграции мини-аппа (см. раздел Интеграция мини-аппа).

Данный метод позволяет изменить текст в заголовке, например, при переходе в другой раздел внутри мини-аппа.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
title
*required
string

Пример:

Параметры запроса:

{
    "title":"Заголовок моего сервиса"
}

Результат:

Заголовок мини-аппа

SetButtonGroup

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

Заголовок (header) мини-аппа является нативным на стороне VK Teams. При вызове данного метода в заголовок добавляются иконки, переданные в параметрах запроса. На каждую иконку добавляется обработчик.

При отрисовке иконки автоматически приобретают тему оформления, выбранную в VK Teams (светлая/тёмная тема, а также окрашивание в акцентный цвет темы).

Иконки отображаются в заголовке мини-аппа на всех платформах VK Teams. Отрисовка разного набора иконок на разных платформах не предусмотрена.

Набор доступных иконок к добавлению в заголовок представлен ниже:

Наименование Иконка
add Иконка add
edit Иконка edit
menu Иконка menu
event Иконка event
send Иконка send
done Иконка done
search Иконка search
more Иконка more
tune Иконка tune
​ ​ ​ ​ ​ ​ ​
Параметры запроса Атрибуты события Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
group string Название панели, для которой устанавливается набор кнопок. Доступные значения:
– headerLeft
• Максимальное количество кнопок для панели — 1
– headerRight
• Максимальное количество кнопок для панели — 2
UNKNOWN_
GROUP
Неизвестное имя группы
buttons [ { icon: string callbackData: string }, ... ] Описание кнопок, устанавливаемых для выбранной панели. icon — одна из:
– add
– edit
– menu
– event
– send
– done
– search
– more
– tune
callbackData — ASCII-строка, задаваемая мини-аппом для возврата в коллбэке при нажатии на кнопку (максимум — 1КБ)
UNKNOWN_
ICON
Одна из переданных иконок не поддерживается
CALLBACK_
DATA_
TOO_LARGE
Размер callbackData для одной из кнопок превышает максимально допустимый размер
TOO_MANY_
BUTTONS
Превышено ограничение на максимальное количество кнопок для панели

Пример

Параметры запроса:

{
    "group": "headerLeft",
    "buttons": [
        {
            "icon": "menu",
            "callbackData": "123"
        }
    ]
}

{
    "group": "headerRight",
        "buttons": [
        {
            "icon": "done",
            "callbackData": "123"
        },
        {
            "icon": "event",
            "callbackData": "123"
        }
    ]
}

Результат:

Добавление иконок слева и справа

Позволяет обработать нажатие на ссылку внутри мини-аппа.

В случае внутренней ссылки VK Teams (например, ссылка на профиль пользователя или группового чата) открывается соответствующий раздел внутри мессенджера. В случае внешней ссылки пользователь видит подтверждение для перехода в браузер.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
url *required string

ShowToast

Позволяет отобразить нативное всплывающее уведомление VK Teams в нижней части экрана по центру приложения.

При вызове данного метода VK Teams показывает нативную toast-нотификацию:

- В Desktop (Windows, macOS и Linux-приложениях) и в Web-клиенте - в нижней части экрана по центру приложения;

- В iOS-приложении - по центру экрана;

- В Android-приложении - в нижней части экрана.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
text
*required
string

Пример

Параметры запроса:

{
    "group": "headerLeft",
    "buttons": [
        {
            "icon": "menu",
            "callbackData": "123"
        }
    ]
}

{
    "group": "headerRight",
        "buttons": [
        {
            "icon": "done",
            "callbackData": "123"
        },
        {
            "icon": "event",
            "callbackData": "123"
        }
    ]
}

Результат:

Добавление иконок слева и справа

Позволяет обработать нажатие на ссылку внутри мини-аппа.

В случае внутренней ссылки VK Teams (например, ссылка на профиль пользователя или группового чата) открывается соответствующий раздел внутри мессенджера. В случае внешней ссылки пользователь видит подтверждение для перехода в браузер.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
url
*required
string

ShowToast

Позволяет отобразить нативное всплывающее уведомление VK Teams в нижней части экрана по центру приложения.

При вызове данного метода VK Teams показывает нативную toast-нотификацию:

  • В Desktop (Windows, macOS и Linux-приложениях) и в Web-клиенте - в нижней части экрана по центру приложения;

  • В iOS-приложении - по центру экрана;

  • В Android-приложении - в нижней части экрана.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
text
*required
string

Пример

Параметры запроса:

{
    "text":"Нотификация в вашем сервисе"
}

Результат на примере VK Teams Desktop:

Нативное уведомление

GetThemeSettings

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

В качестве ответа VK Teams возвращает:

  • colorsScheme - признак, обозначающий светлую или тёмную тему;
  • colors - набор цветов, используемых в приложении VK Teams, сконвертированных в токены библиотеки VK UI.
Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
Объект с параметрами
ответа возвращается в
формате ThemeDescription
библиотеки vkui-tokens .
На данный момент
возвращаются поля:
- colors , содержащее
объект ColorsDescriptionStruct
со значениями типа
ColorDescriptionStatic
- colorsScheme ,
содержащее 'light' или 'dark'
Пример возвращаемого объекта

Пример

Ответ, который приходит при вызове данного запроса в VK Teams Web-версии:

{
  "colorsScheme": "light",
  "colors": {
    "colorTextPrimary": "#111111ff",
    "colorBackgroundContent": "#ffffffff",
    "colorAccentBlue": "#1b85f1ff",
    "colorIconAccent": "#2d90f5ff",
    "colorStrokeAccent": "#2d90f5ff",
    "colorBackgroundSecondary": "#f3f5f8ff",
    "colorIconSecondary": "#838690ff",
    "colorTextSecondary": "#838690ff",
    "colorSeparatorPrimaryAlpha": "rgba(0,0,0,0.05)",
    "colorBackground": "#f6f6f6ff",
    "colorSeparatorPrimary": "#cccfd8ff"
  }
}

Позволяет получить ссылку на страницу мини-аппа, интегрированного в VK Teams, зная его ID.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
miniappId string ID мини-аппа, на который требуется получить ссылку. В случае отсутствия данного параметра будет сгенерирована ссылка на текущий мини-апп. url
*required
string Публичная ссылка на мини-апп.

Пример

Параметры запроса:

{
    "miniappId":"miniapp_id"
}

Ответ:

{
  "url": "https://u.vkteams-test-domain.team/miniapp/miniapp_id"
}

GetLanguage

Позволяет мини-аппу узнать язык, выбранный в данный момент в клиенте VK Teams, для последующего применения в мини-аппе.

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

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
language
*required
string Код языка в соответствии со стандартом RFC5646

Пример

Ответ:

{
  "language": "ru"
}

OpenPopUp

Позволяет отобразить нативное окно подтверждения VK Teams с двумя доступными действиями: главная кнопка, а также вторичная.

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

Параметры запроса Атрибуты события Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
title string Заголовок окна feedback
*required
string main или secondary в зависимости от того, какую кнопку нажал пользователь POPUP_CLOSED Окно было закрыто
text
*required
string Основной текст BAD_REQUEST Поле text, mainButton или secondary
Button пусто
mainButton
*required
string Текст основной кнопки (акцентный цвет)
secondaryButton
*required
string Текст вторичной кнопки

Пример

Параметры запроса:

{
    "text":"Подтверждаете операцию?",
    "mainButton":"Да",
    "secondaryButton":"Нет"
}

Результат:

Подтверждение действия

StoragePut

Работа с персистентным хранилищем. Позволяет добавить пару ключ-значение в персистентное хранилище.

Параметры запроса Атрибуты события Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
key
*required
string Ключ.
Максимальный размер ограничен значением omicron-переменной miniapp-storage-key-max-size (в байтах, дефолт — 10М)
KEY_IS_TOO
_LARGE
Превышено ограничение на размер ключа
value
*required
string Значение.
Максимальный размер ограничен значением omicron-переменной miniapp-storage-value-max-size (в байтах, дефолт — 10М)
VALUE_IS_TOO
_LAGRE
Превышено ограничение на размер значение
TOTAL_LIMIT_
EXCEEDED
Превышено ограничение на суммарный размер всех записей, хранящихся в персистентном хранилище мини-аппа. Максимальный размер ограничен значением omicron-переменной miniapp-storage-total-max-size (в байтах, дефолт — 10М)

StorageGet

Работа с персистентным хранилищем. Позволяет получить значение из персистентного хранилища.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
key
*required
string Ключ value
*required
string Значение KEY_NOT_FOUND Ключ не найден

StorageDelete

Работа с персистентным хранилищем. Позволяет удалить пару ключ-значение из персистентного хранилища.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
key
*required
string Ключ KEY_NOT_FOUND Ключ не найден

StorageClear

Работа с персистентным хранилищем. Позволяет удалить пару ключ-значение из персистентного хранилища.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание

StartAudioCall

Позволяет начать голосовой звонок VK Teams с пользователем.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
userId
*required
string Пользователь, которому будет выполнен вызов USER_NOT_FOUND Пользователь с таким id не найден

StartVideoCall

Позволяет начать видеозвонок VK Teams с пользователем.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
userId
*required
string Пользователь, которому будет выполнен вызов USER_NOT_FOUND Пользователь с таким id не найден

OpenAuthModal

Позволяет открыть модальное окно для выполнения пользователем аутентификации.

По окончании аутентификации, страница аутентификации должна выполнить редирект на указанный в параметрах адрес для закрытия модального окна и передачи информации мини-аппу.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
url
*required
string Адрес, который будет открыт в модальном окне querystring
*required
string Параметры, переданные при выполнении редиректа MODAL_CLOSED Модальное окно было закрыто пользователем
redirectUrl
ParamName

*required
string Имя, под которым в url будет добавлен адрес для возврата результата из модального окна в Mini App путём выполнения редиректа на этот адрес

SetCanGoBack

Позволяет уведомить основное приложение о возможности перехода на предыдущее состояние в навигации по мини-аппу.

При использовании данного запроса приложение VK Teams обрабатывает кнопку Назад как возврат на предыдущий раздел мини-аппа.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание

SetCanNotGoBack

Позволяет уведомить основное приложение о невозможности перехода на предыдущее состояние в навигации по мини-аппу.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание

OpenContactSelectionDialog

Позволяет открыть нативное модальное окно / экран VK Teams с выбором контактов среди контактов мессенджера.

Параметры запроса Атрибуты события Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
title
*required
string, not empty Заголовок окна contacts [ { id: string, type: string, }, ... ] Выбранные пользователем контакты. id — SN пользователя, бота, группы или канала type — один из:
• user;
• bot;
• group;
• channel.
BAD_
REQUEST
Поле title или confirm
Button содержит пустую строку, filter содержит пустой массив или в массиве filter есть пустые строки, или не выполнены прочие ограничения на типы данных или домены значений
multiple boolean Разрешить выбор нескольких контактов. При true в окне с контактами доступны чекбоксы для выбора нескольких контактов. При false мультивыбор (чекбоксы) отсутствуют, и выбор контакта сразу закрывает окно. Если параметр не передан, применяется значение false. MODAL_
CLOSED
Модальное окно / экран было закрыто пользователем при помощи кнопки Отмена
maxCount integer, >= 1 Максимальное количество контактов для выбора, в случае multiple=true. При multiple=false значение maxCount игнорируется и принимает значение 1.
filter [] string Фильтрация по типам контактов, доступных к выбору пользователем. Доступные значения:
• users — пользователи;
• bots — боты;
• groups — группы;
• channels — каналы.
В будущем могут появляться новые значения, поэтому для обратной совместимости незнакомые значения в массиве игнорируются. Заблокированные, игнорируемые контакты, а также "Избранное" не отображаются никогда. Если параметр отсутствует, то к выбору доступны все типы контактов.
writable
Only
boolean Отображать только контакты, которым можно написать сообщение. При true группы и каналы с ролью readonly не будут отображаться в диалоге выбора контактов. При отсутствии параметра значение по умолчанию = false.
confirm
Button
string, not empty Текст, отображаемый на кнопке подтверждения выбора контактов в случае multiple=true. Если параметр отсутствует, отображается дефолтный текст "ОК". При multiple=false кнопка отсутствует. В мобильных клиентах кнопка прячется, пока никто не выбран, и появляется, как только выбран хотя бы один контакт. На Desktop & Web кнопка сразу есть, но заблокирована пока никто не выбран.

Пример

Параметры запроса:

{
    "title": "Заголовок для выбора пользователей",
    "multiple": true,
    "maxCount": 5,
    "filter":[
        "users"
    ],
    "writableOnly": false,
    "confirmButton": "Выбрать!"
}

Результат:

Подтверждение действия

GetSelfId

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

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
userId string SN текущего пользователя

DownloadFile

Позволяет обработать процедуру скачивания файла из мини-аппа на стороне VK Teams.

Параметры запроса Поля ответа Специфичные коды ошибок
Имя Тип Описание Имя Тип Описание Код Описание
url
*required
string Ссылка на файл

Подписка на события от основного приложения (метод subscribe)

Помимо отправки запросов, есть также возможность подписки на события, возникающие в нативном приложении VK Teams.

Аргументы функции:

  • Название подписки (string);

  • Функция для обработки событий;

  • Параметры подписки (object). //в случае, если у подписки нет параметров — null

Результат в случае ошибки — объект с полями:

  • code (string); //содержит код ошибки

  • reason (string). //содержит описание ошибки

Общий формат вызова метода

bridge.subscribe(
  <название подписки>, // string
  ({ <атрибуты события> }) => { ... } // функция-обработчик события
  {
    <параметры подписки>
  }
).catch(({
  code,   // string
  reason, // string
}) => {
  <обработка ошибки подписки>
})

Общие коды ошибок

- UNKNOWN_SUBSCRIPTION_NAME.

Перечень и описание подписок

ThemeSettings

Настройки темы.

Параметры подписки Атрибуты события Специфичные коды ошибок подписки
Имя Тип Описание Имя Тип Описание Код Описание
См. поля ответа на запрос GetThemeSettings метода send

Language

Настройки языка.

Параметры подписки Атрибуты события Специфичные коды ошибок подписки
Имя Тип Описание Имя Тип Описание Код Описание
См. поля ответа на запрос GetLanguage метода send

BackButtonPressed

Пользователь нажал кнопку Назад. Необходимо выполнить переход на предыдущее состояние в навигации по мини-аппу.

Параметры подписки Атрибуты события Специфичные коды ошибок подписки
Имя Тип Описание Имя Тип Описание Код Описание




Дата обновления документа: 15.09.2023 г.