Строить там, где уже есть пользователи: Telegram Mini Apps

Проблема дистрибуции

Вот в чём дело со строительством для Центральной Азии: ваши пользователи уже в Telegram. Не "некоторые пользователи" — практически все. Проникновение Telegram здесь не такое, как где-либо ещё. Так что когда я думал, как распространить пользовательский интерфейс бронирования BookUp, ответ был довольно очевидным.

Зачем убеждать кого-то скачивать приложение или запоминать URL, когда они всё равно будут в Telegram?

Что мы на самом деле построили

Для BookUp Telegram Mini App — это основной клиентский интерфейс. Кто-то хочет забронировать в барбершопе — открывает бота, мини-приложение загружается внутри Telegram, выбирает время, готово. Никакого нового приложения для установки. Никакого логина — Telegram управляет идентификацией.

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

Auth-поток на самом деле умный

Способ, которым Telegram передаёт идентификацию пользователя в мини-приложение, интересен. При загрузке приложения Telegram инжектирует строку initData в JavaScript-контекст. Она содержит данные пользователя (ID, имя, username) и хеш.

Для проверки подлинности нужно провалидировать HMAC:

import crypto from 'crypto';

function verifyInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');

  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');

  const secretKey = crypto
    .createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();

  const expectedHash = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  return hash === expectedHash;
}

После верификации на бэкенде можно доверять идентификации пользователя и выдавать собственный сессионный токен.

Особенности, которые вас поймают

Кнопка назад — ненастоящая. Telegram предоставляет "кнопку назад" в заголовке, но это не реальная кнопка браузера — это событие, которое нужно обрабатывать в JavaScript.

Клавиатура на iOS... особенная. Когда текстовый ввод получает фокус на iOS внутри Telegram Mini App, viewport смещается иначе, чем в обычном Safari WebView. Много багов "ввод скрыт за клавиатурой".

Layout viewport vs visual viewport. Telegram предоставляет window.Telegram.WebApp.viewportStableHeight — используйте его для layout.

Переменные темы — подарок. Telegram передаёт CSS-переменные для текущей темы пользователя. Использование их делает приложение нативным для скина Telegram пользователя.

Честные плюсы и минусы

Плюсы: почти нулевое трение дистрибуции, не нужна проверка App Store, мгновенные обновления, идентификация бесплатно, пользователи уже там.

Минусы: вы строите внутри чужого контейнера. Telegram может изменить API. Отладка сложнее.

Для рынков, на которые я строю, плюсы явно побеждают.