Telegram Mini App яратиш ва хостингга жойлаш: HTTPS, BotFather ва initData

Telegram Mini App фойдаланувчига ботдан чиқмасдан тўлиқ интерфейсга эга иловадан фойдаланиш имконини беради: каталог кўриш, саватча тўлдириш, жой банд қилиш ёки анкета тўлдириш. Техник жиҳатдан бу оддий веб-саҳифа бўлиб, Telegram уни ўз ичидаги браузер ойнасида очади ва унга махсус JavaScript объекти орқали фойдаланувчи, мавзу ранглари ва тугмалар билан ишлаш имконини беради. Демак, Mini App учун алоҳида "Telegram сервери" керак эмас, уни одатий сайт каби хостингга жойлаш мумкин. Қуйида Самарқанддаги нон дўкони учун буюртма иловаси мисолида бутун жараённи кўриб чиқамиз.

Mini App нималардан ташкил топади

Одатда Mini App икки қисмдан иборат. Биринчиси фронтенд: HTML, CSS ва JavaScript файллари, улар React, Vue ёки оддий JavaScript билан ёзилиши мумкин. Иккинчиси бэкенд: буюртмаларни қабул қиладиган, базага ёзадиган ва фойдаланувчини текширадиган API. Кичик лойиҳаларда иккаласи битта доменда туради, масалан фронтенд app.misol.uz илдизида, API эса app.misol.uz/api/ манзилида. Бу схема CORS созламалари билан боғлиқ ортиқча муаммоларни олдини олади.

Фронтенд статик файллар тўплами бўлгани учун уни деярли исталган хостингга жойлаш мумкин. Бэкенд PHP'да ёзилган бўлса, оддий shared хостинг ҳам етарли; Node.js ёки Python'да ёзилган бўлса, доимий жараённи ушлаб туриш учун VPS қулайроқ бўлади. Нон дўкони мисолида фронтенд Vite билан йиғилган, бэкенд эса бир нечта PHP скриптдан иборат ва MySQL базасидан фойдаланади.

Хостинг ва HTTPS тайёрлаш

Telegram Mini App манзили албатта HTTPS бўлиши керак, оддий HTTP манзилни BotFather қабул қилмайди. Шунинг учун биринчи қадам субдомен яратиб, унга SSL сертификатини ўрнатишдир. sayt.uz хостингида бу иш кабинет орқали бажарилади: субдомен қўшилади, унга бепул Let's Encrypt сертификати уланади ва сертификат муддати тугашидан олдин автоматик янгиланади. Сертификат янгиланмай қолса, Mini App фойдаланувчиларда оқ экран билан очилади, шунинг учун автоматик янгиланиш бу ерда жуда муҳим.

Фронтендни build қилгач, dist папкасидаги файлларни субдоменнинг илдиз каталогига юкланг. Агар илова клиент томонида маршрутлашдан фойдаланса, барча номаълум манзилларни index.html файлига йўналтириш керак. Apache ишлатиладиган хостингда буни .htaccess файли билан қилиш мумкин:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/api/
RewriteRule ^ index.html [L]

Фронтенд: telegram-web-app.js билан ишлаш

Telegram билан алоқа расмий скрипт орқали ўрнатилади. У саҳифага window.Telegram.WebApp объектини қўшади. ready() методи Telegram'га илова юкланганини билдиради, expand() эса ойнани тўлиқ баландликка очади. Пастдаги асосий тугма MainButton орқали бошқарилади ва у Telegram дизайнига мос кўринади.

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
  const tg = window.Telegram.WebApp;
  tg.ready();
  tg.expand();
  tg.MainButton.setText("Buyurtma berish").show();
  tg.MainButton.onClick(async () => {
    await fetch("/api/order.php", {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-Init-Data": tg.initData },
      body: JSON.stringify({ items: cart })
    });
    tg.close();
  });
</script>

Илова рангларини қўлда танлаш ўрнига tg.themeParams қийматларидан фойдаланиш тавсия этилади. Шунда Mini App фойдаланувчининг кундузги ёки тунги мавзусига мослашади ва Telegram ичида бегонадек кўринмайди.

Энг муҳим қисм: initData'ни серверда текшириш

Фронтенд фойдаланувчи ҳақидаги маълумотни икки кўринишда олади: initDataUnsafe объекти ва initData сатри. Номидан ҳам кўриниб турибдики, биринчисига ишониб бўлмайди, чунки браузердаги исталган қийматни сохталаштириш мумкин. Тўғри йўл initData сатрини серверга юбориб, унинг имзосини бот токени ёрдамида текширишдир. Telegram ҳужжатларига кўра калит WebAppData сўзи ва бот токенидан HMAC-SHA256 орқали ҳосил қилинади, сўнг сараланган майдонлар сатри шу калит билан имзоланади.

function tg_check_init_data(string $initData, string $botToken): ?array {
    parse_str($initData, $data);
    if (empty($data['hash'])) return null;
    $hash = $data['hash'];
    unset($data['hash']);
    ksort($data);
    $pairs = [];
    foreach ($data as $k => $v) $pairs[] = $k . '=' . $v;
    $secret = hash_hmac('sha256', $botToken, 'WebAppData', true);
    $calc = hash_hmac('sha256', implode("\n", $pairs), $secret);
    if (!hash_equals($calc, $hash)) return null;
    if (time() - (int)($data['auth_date'] ?? 0) > 86400) return null;
    return $data;
}

Функция имзо тўғри бўлса майдонлар массивини қайтаради, user майдони эса JSON кўринишида бўлиб, уни json_decode билан ўқиш мумкин. auth_date текшируви эски, ушлаб қолинган сўровларни қайта ишлатишдан ҳимоя қилади. Бот токени фақат серверда, масалан веб-каталогдан ташқаридаги конфигурация файлида сақланиши керак.

BotFather орқали ботга улаш

Илова тайёр бўлгач, уни ботга боғлаш қолади. Бунинг бир нечта усули бор ва уларни биргаликда ишлатиш ҳам мумкин:

Меню тугмаси: BotFather'да бот созламаларидан меню тугмасини созлаб, унга https://app.misol.uz манзилини берасиз.
Тўғридан-тўғри ҳавола: /newapp буйруғи билан илова яратиб, уни алоҳида ҳавола орқали улашиш мумкин.
Клавиатура тугмаси: бот хабарида web_app туридаги тугма юбориб, иловани муайян суҳбат ичидан очиш мумкин.

Синов пайтида Telegram ички браузери саҳифани кешлаб қолиши мумкин, шунинг учун янги build юклагандан кейин файл номларида хеш бўлишига эътибор беринг; Vite ва бошқа замонавий йиғувчилар буни автоматик бажаради. Хатоларни топиш учун Telegram Desktop ёки Android иловасидаги веб-текширув имкониятлари ҳақида расмий ҳужжатларни кўриб чиқинг.