SMeet Mini Apps

Быстрый старт

От бота до работающей тестовой версии за семь шагов. Нужны свой бот, сервер с HTTPS и около получаса.

Что нужно#

Свой бот в SMeet. Если его ещё нет, создайте его в SMeet BotFather (Быстрый старт Bot API).
Два origin с HTTPS под вашим управлением, один для рабочей версии и один для тестовой, например https://forms.example.com и https://test.forms.example.com. Адреса на scrile.com и IP-адреса не принимаются (Адреса).
Для примеров: Node.js 22.13 или новее либо Python 3.9 или новее.

1. Создайте мини-приложение#

Откройте в SMeet «Мои боты», выберите бота и откройте Мини-приложение; в SMeet BotFather на тот же экран ведёт /miniapp. Прочитайте и примите Правила для авторов, затем нажмите Создать мини-приложение.

Заполните настройки:

название и описание, которые люди видят на экране согласия;
адрес рабочей и адрес тестовой версии, то есть страницы, которые открывают люди, например https://forms.example.com/ и https://test.forms.example.com/;
ссылки на вашу политику конфиденциальности и на поддержку, обе https://;
что получает приложение: идентификатор и язык всегда, отображаемое имя только если отмечено Имя человека;
Отправка результата боту, если страница вызывает submitToBot();
возрастную категорию; сейчас принимается только 4+.

2. Подтвердите домены#

Для каждой версии экран показывает токен подтверждения. Разместите его текстовым файлом по адресу /.well-known/smeet-mini-app.txt этого origin, на отдельной строке, и нажмите Проверить:

Text

https://test.forms.example.com/.well-known/smeet-mini-app.txt

smeet-mini-app-Fy3xK0wQm9PZ2s7vTn4cLbJ8hR5dW1eGqA6uYt2N

Та же проверка читает заголовки адреса каждой версии. Отдавайте этот заголовок с каждой страницей приложения, чтобы показывать её во фрейме мог только SMeet:

HTTP

Content-Security-Policy: frame-ancestors https://messenger.scrile.com

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

3. Выпустите ключ#

В разделе Ключи вашего сервера выпустите ключ для тестовой версии. Он показывается один раз: сразу поместите его в окружение сервера, например в MINI_APP_KEY. Ключом сервер обменивает коды входа и проверяет сессии; на страницу он не попадает. У каждой версии свои ключи (Ключи).

4. Запустите пример#

Скачайте пример и запустите его на тестовом origin:

smeet-mini-apps-forms.zip: анкета, которая уходит боту, Node.js без пакетов;
smeet-mini-apps-desk.zip: служба заявок с файлами и outbox, Node.js и PostgreSQL;
smeet-mini-apps-python-minimal.zip: вход, проверка сессии и ответ бота, Python без пакетов.

Для анкеты:

Shell

unzip smeet-mini-apps-forms.zip && cd smeet-mini-apps-forms/examples/forms
cp .env.example .env
# в .env: MINI_APP_ENVIRONMENT=test, MINI_APP_KEY=<ключ>, SMEET_BOT_TOKEN=<токен бота>, BOT_MODE=polling
node build.mjs --out dist --api-path /api/
STATIC_DIR=./dist node --env-file=.env server.mjs

Тестовый процесс слушает 127.0.0.1:5102; поставьте перед ним свой обратный прокси с HTTPS для тестового origin. Заголовок frame-ancestors https://messenger.scrile.com к странице он добавляет сам. BOT_MODE=polling делает этот процесс получателем событий бота, и бот отвечает на анкеты; у бота ровно один получатель, поэтому, когда заработает рабочий процесс, эту роль берёт он, а тестовый получает BOT_MODE=off. В каждом архиве есть README со всеми настройками (Примеры).

5. Откройте тестовую версию#

Экран показывает ссылку на тестовую версию: https://messenger.scrile.com/u/<bot>?startapp=&env=test. Откройте её в SMeet. Сначала появится экран согласия с пометкой «Тестовая версия, SMeet её не проверял», затем ваша страница в окне.

Если окно пишет «Приложение не отвечает или запрещает встраивание», страница не подключилась за 15 секунд: проверьте заголовок frame-ancestors и то, что страница подключает SDK в своём <head> (Когда окно показывает ошибку).

Тестировщиков приглашайте по имени пользователя в разделе Тестировщики; тестовую версию они открывают, когда примут приглашение.

6. Отправьте на проверку#

Когда оба домена подтверждены, встраивание ограничено SMeet для обеих версий, а ссылки на политику и поддержку указаны, нажмите Отправить на проверку. Мини-приложения публичного пространства SMeet проверяют модераторы SMeet, мини-приложения организации проверяют её владелец и администраторы (Проверка).

7. Дайте людям его открыть#

После публикации рабочая версия открывается кнопкой mini_app, которую ваш бот присылает в личном чате, и ссылкой https://messenger.scrile.com/u/<bot>?startapp=<param>:

JSON

{"text": "Открыть анкету", "mini_app": {"start_param": "vpn-access"}}

Страница читает параметр как environment.startParam, а ваш сервер получает его как start_param при обмене (Кнопка mini_app).

Дальше#

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