Мини-приложения

Мини-приложение — это ваш сайт, который открывается в окне Yobi. Он получает данные пользователя с подписью сервера, управляет кнопками интерфейса и хранит данные в облаке. Протокол совместим с Telegram Web Apps, поэтому готовые мини-приложения работают без переделок.

Как открыть мини-приложение

Пользователь попадает в мини-приложение одним из способов:

• кнопка под сообщением — InlineKeyboardButton с полем web_app;
• кнопка клавиатуры — KeyboardButton с web_app; такое приложение может отправить данные боту через sendData;
• кнопка меню бота — /setmenubutton у @BotMaker или метод setChatMenuButton;
• меню вложений — приложения, добавленные в «скрепку», доступны в группах и каналах, а в личном диалоге — в окне «Игры и приложения»;
• игра для двоих — действие бота в окне «Игры и приложения», см. Игры и приложения;
• каталог — главное приложение бота находится в глобальном поиске Yobi;
• кнопка «Открыть» в списке чатов — у бота с главным мини-приложением справа в строке чата; по умолчанию включена, выключается командой /setlistbutton у @BotMaker или методом setChatListButton ({"enabled": false});
• ссылка — https://yobi.chat/<бот>?startapp=<параметр> открывает главное приложение, параметр приходит в initDataUnsafe.start_param.

Мини-приложение открывается только после того, как пользователь сам запустил бота. Если бот ещё не запущен, Yobi открывает чат с ботом с кнопкой «Запустить»; после нажатия бот получает /start, а приложение открывается автоматически.

Подключение

Добавьте на страницу скрипт моста. Он совместим с официальным telegram-web-app.js и создаёт объект window.Telegram.WebApp.

<script src="https://yobi.chat/js/telegram-web-app.js"></script>
<script>
  const app = Telegram.WebApp;
  app.ready();
  app.MainButton.setText('Оформить заказ').show();
  app.MainButton.onClick(() => app.sendData(JSON.stringify({ order: 42 })));
</script>

Пример приложения: https://yobi.chat/webapp/demo.

Данные пользователя

Telegram.WebApp.initData — строка параметров с данными пользователя, временем auth_date и подписью hash. Не доверяйте initDataUnsafe: перед использованием проверьте подпись на своём сервере.

secret = HMAC_SHA256(key = "WebAppData", msg = <токен бота>)
hash   = hex(HMAC_SHA256(key = secret, msg = data_check_string))

data_check_string — все пары ключ=значение, кроме hash, отсортированные по ключу и соединённые переводом строки \n.

Интерфейс

Свернуть и развернуть

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

• Telegram.WebApp.isActive — развёрнуто ли приложение сейчас; события activated и deactivated приходят, когда его разворачивают и сворачивают. Остановите таймеры и анимации в фоне, если они не нужны.
• Telegram.WebApp.requestFullscreen() и exitFullscreen() разворачивают приложение на весь экран и возвращают обычный размер; isFullscreen и событие fullscreenChanged сообщают о текущем режиме. Пользователь может переключить режим и сам — кнопкой в заголовке.

Облачное хранилище

Telegram.WebApp.CloudStorage хранит пары ключ–значение для пары «пользователь — бот» на сервере Yobi. Данные доступны на всех устройствах пользователя.

const cs = Telegram.WebApp.CloudStorage;
cs.setItem('cart', JSON.stringify(cart));
cs.getItem('cart', (err, value) => render(JSON.parse(value || '[]')));
cs.getKeys((err, keys) => console.log(keys));
cs.removeItem('cart');

Ответ боту

• Приложение из кнопки клавиатуры вызывает sendData(строка) — бот получает сообщение с полем web_app_data, окно закрывается.
• Приложение из кнопки под сообщением или меню получает query_id и отвечает через метод бота answerWebAppQuery — в чат приходит сообщение от имени пользователя.

Каталог

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