Как казино интегрирует Telegram WebApp

Зачем казино Telegram WebApp

Низкое трение: вход в 1–2 тапа из диалога с ботом, без «поиска сайта».

Мгновенная доставка фич: фронтенд живёт на вашем домене, релизы через CDN.

Привязка к Telegram-профилю: понятный идентификатор пользователя и готовые каналы коммуникации (бот-сообщения вместо пушей).

Маркетинг-охват: ссылки `t.me/…` и кнопки в каналах/чатах.

💡 Важно: в Telegram действуют собственные правила для платежей и контента. Для гэмблинга соблюдайте юрисдикции, блокировки гео и условия площадки. Часть платёжных сценариев лучше выводить во внешний браузер (см. раздел «Касса и ограничения»).

Архитектура: из чего состоит интеграция

Компоненты:

1. Bot API-слой (webhook/long-polling): принимает команды, шлёт меню, запускает WebApp.

2. WebApp (SPA/PWA) на вашем домене: лобби, профиль, промо, лёгкие игровые сцены, касса-роутер.

3. Платформенный API казино: аутентификация, баланс/ставки, бонусы, касса, истории.

4. Хранилище сессий/линковки: связка `telegram_user_id ↔ account_id`.

5. CDN + анти-бот/фрод: защита и раздача ассетов мини-приложения.

Поток запуска:

Пользователь пишет боту → нажимает кнопку «Открыть» (web_app).
Telegram встраивает ваше WebApp в клиент и передаёт вам `initData` (подписанные параметры пользователя/чата).
WebApp проверяет подпись на бэкенде → создаёт/возобновляет сессию в казино → отдаёт UI.

Запуск WebApp: кнопки и deep-link

Варианты:

Кнопка в ReplyKeyboard/InlineKeyboard c `web_app: {url: "https://your.app/tg"}` — открывает мини-приложение внутри Telegram.
Main Menu (BotFather → Menu Button) — постоянная кнопка «Открыть».
Deep-link `https://t.me/?startapp=` — прокиньте стартовый контекст (например, промо/реферал/игра).

Совет: используйте `startapp` для безопасной передачи «намерения» (какой экран открыть). Сам контент и права определяйте уже после проверки подписи.

Аутентификация и линковка аккаунта

Что приходит в WebApp

Клиент Telegram добавляет в окно JS-объект `Telegram.WebApp` и строку `initData`/`initDataUnsafe` — сведения о пользователе/чате, времени и подпись.

Как подтвердить пользователя

1. На фронте возьмите `Telegram.WebApp.initData` и отправьте его как есть на ваш бэкенд.

2. На бэкенде проверьте подпись по алгоритму Telegram (HMAC-SHA256 на строке данных c ключом, производным от токена бота; точный алгоритм — в официальной документации Telegram).

3. Если проверка успешна — извлеките `user.id`, `username` и метаданные → найдите или создайте связку `telegram_user_id ↔ account_id`.

4. Выдайте фронту короткоживущий JWT/сессионный токен платформы казино (например, TTL 10–30 мин + refresh по безопасному API).

💡 Никогда не доверяйте `initData` без проверки подписи на сервере. Не используйте «user_id из фронта» как единственный источник истины.

Обмен данными бот ↔ WebApp

Из WebApp в бота: `Telegram.WebApp.sendData(JSON.stringify(payload))` — бот получит `web_app_data` и может ответить сообщением/кнопкой.

События UI внутри WebApp: `MainButton`, `BackButton`, `HapticFeedback`, `onEvent('themeChanged'	'viewportChanged'	…)`.
Закрытие мини-приложения: `Telegram.WebApp.close()` — удобно после «успешно выполнено».

Паттерн: сложные операции (касса, верификация) ведём в WebApp; бот — для триггеров/уведомлений («бонус активирован», «KYC одобрен»).

Касса и ограничения платформ

Платежи в Telegram: у платформы есть встроенные платежные механики и отдельные правила по категориям. Для гэмблинга применяйте локальные законы и политику Telegram.

Практический подход:

Чек-аут открывайте во внешнем браузере (deeplink `target=_blank`) с полноценным KYC/AML/KYT-контуром и idempotency-ключами.
Для пополнений/выводов показывайте только допустимые для страны пользователя методы (гео-фенсинг).
Всегда дублируйте подтверждения в чат бота (как замену пушам).

UX: как сделать «нативно» и быстро

Тема/цвета: используйте `Telegram.WebApp.themeParams` и `colorScheme` (light/dark), меняйте в рантайме по `themeChanged`.

Навигация: `MainButton.setText('Продолжить').show()`; `BackButton.show()` и обработчик `onEvent('backButtonClicked',…)`.

Viewport: `Telegram.WebApp.expand()`; следите за `viewportHeight` (особенно на iOS).

Локализация: берите язык из `initDataUnsafe.user.language_code` + свой i18n.

Производительность: PWA + Service Worker, CDN с hash-ассетами, lazy-chunks. Первый экран ≤ 150–200 КБ br.

Микро-пример (фронт):

html
<script>
const tg = window.Telegram.WebApp;
tg.expand();
tg.MainButton.setText('Открыть лобби').show().onClick(() => {
// отправим сигнал боту (необязательно), либо просто роутим внутри SPA tg.HapticFeedback.impactOccurred('medium');
});
// передаём initData на сервер для верификации fetch('/api/tg/auth', {method:'POST', headers:{'Content-Type':'application/json'},   body: JSON.stringify({ initData: tg.initData })});
</script>

Безопасность: обязательные меры

Проверка подписи `initData` на сервере. Храните «свежее окно» (напр., 1–5 мин) — старые подписи отклоняйте.

Связка идентичностей: `telegram_user_id` — атрибут профиля, но доступ к деньгам всегда через ваш токен/сессию.

Вебхуки бота: секретный путь (`/bot` или собственный заголовок), IP-allowlist Telegram, таймауты/идемпотентность.

Анти-бот: device-fingerprint и поведенческие сигналы в WebApp, rate-limit по `telegram_user_id` и IP.

Контент-безопасность: CSP для домена мини-аппа, `X-Frame-Options` не мешает встраиванию в Telegram, строгий CORS к API.

Логи и PII: маскируйте, храните по GDPR/локальным нормам, используйте WORM для платежных/игровых событий.

Телеметрия и аналитика

RUM: TTFB/LCP/TTI внутри WebApp; события «open_from_deeplink», «auth_ok», «deposit_start/success», «bet_place».

Каналные метки: прокидывайте реферала/utm через `startapp` → связывайте с сессией казино.

SLO: p95 `auth_via_initData` ≤ 200–300 мс, p95 «первый экран» ≤ 2 с, ошибка проверки подписи < 0.1%.

Фрод-сигналы: аномалии по странам/часам/устройствам, массовые открытия без действий, повторяющиеся `startapp`.

Типовой backend-контур (псевдокод)

pseudo
POST /api/tg/auth { initData }
assert verifyTelegramSignature(initData)  // строго по докам Telegram let tgUser = parse(initData)
let account = findOrCreateByTelegram(tgUser.id)
let session = issueJWT(account_id, ttl=20m, scope='webapp')
return { token: session.jwt, account }

POST /api/cashier/deposit { token, method, amount }
assert auth(token)
assert geoAllowed(account.country)
createIdempotencyKey()
redirectToPSP(...) // во внешний браузер

POST /api/bot/webhook verifyTelegramSignatureOrSecret()
handle commands, web_app_data, callbacks reply with messages/buttons

Чек-лист запуска Telegram WebApp для казино

Право и политика

Юрисдикции, гео-блокинг, тексты RG/KYC в локали.
Политика Telegram для вашей категории, белые списки стран/каналов.

Аутентификация

Серверная проверка подписи `initData` (включая окно свежести).
Линковка `telegram_user_id ↔ account_id`, короткие JWT.

Касса

Вывод чек-аута во внешний браузер (где нужно), idempotency, KYC/KYT.
Гео-зависимые методы, дублирование статусов бот-сообщениями.

Фронтенд

Тема/цвета из `themeParams`, `MainButton/BackButton`, `expand()`.
PWA/SW, CDN с hash-ассетами, LCP ≤ 2 с.

Безопасность

Вебхуки: секрет/allowlist/таймауты.
Rate-limits, анти-бот, CSP/CORS.
Логи WORM для денег/игр; PII-маскирование.

Аналитика

RUM метрики, события онбординга/кассы/ставок.
Канальная атрибуция через `startapp`.

Анти-паттерны

Доверять `initData` на фронте без серверной верификации.

Пытаться «втискивать» полный чек-аут в WebApp, игнорируя политику/юрисдикции.

Хардкодить тему/цвета → нечитаемо в тёмной/светлой теме Telegram.

Отсутствие idempotency в кассе и вебхуках бота.

Долгоживущие сессии без ротации и отзыва.

Монолитный бандл 5–10 МБ → медленный первый экран и отвал сессии.

Интеграция Telegram WebApp даёт казино быстрый вход, удобную коммуникацию и «легковесный» клиент без установки. Успех — в правильной аутентификации через `initData`, аккуратной линковке аккаунта и соблюдении политик платежей/контента. Добавьте нативный UX (тема, кнопки, хаптика), CDN-поставку ассетов, строгую безопасность и измеримую аналитику — и мини-приложение станет эффективным acquisition- и retention-каналом, который масштабируется без боли.