Telegram Mini App foydalanuvçiga botdan çiqmasdan töliq interfeysga ega ilovadan foydalaniş imkonini beradi: katalog köriş, savatça töldiriş, joy band qiliş yoki anketa töldiriş. Texnik jihatdan bu oddiy veb-sahifa bölib, Telegram uni öz içidagi brauzer oynasida oçadi va unga maxsus JavaScript obyekti orqali foydalanuvçi, mavzu ranglari va tugmalar bilan işlaş imkonini beradi. Demak, Mini App uçun alohida "Telegram serveri" kerak emas, uni odatiy sayt kabi hostingga joylaş mumkin. Quyida Samarqanddagi non dökoni uçun buyurtma ilovasi misolida butun jarayonni körib çiqamiz.
Mini App nimalardan taşkil topadi
Odatda Mini App ikki qismdan iborat. Birinçisi frontend: HTML, CSS va JavaScript fayllari, ular React, Vue yoki oddiy JavaScript bilan yozilişi mumkin. Ikkinçisi backend: buyurtmalarni qabul qiladigan, bazaga yozadigan va foydalanuvçini tekşiradigan API. Kiçik loyihalarda ikkalasi bitta domenda turadi, masalan frontend app.misol.uz ildizida, API esa app.misol.uz/api/ manzilida. Bu sxema CORS sozlamalari bilan boğliq ortiqça muammolarni oldini oladi.
Frontend statik fayllar töplami bölgani uçun uni deyarli istalgan hostingga joylaş mumkin. Backend PHP'da yozilgan bölsa, oddiy shared hosting ham yetarli; Node.js yoki Python'da yozilgan bölsa, doimiy jarayonni uşlab turiş uçun VPS qulayroq böladi. Non dökoni misolida frontend Vite bilan yiğilgan, backend esa bir neçta PHP skriptdan iborat va MySQL bazasidan foydalanadi.
Hosting va HTTPS tayyorlaş
Telegram Mini App manzili albatta HTTPS bölişi kerak, oddiy HTTP manzilni BotFather qabul qilmaydi. Şuning uçun birinçi qadam subdomen yaratib, unga SSL sertifikatini örnatişdir. sayt.uz hostingida bu iş kabinet orqali bajariladi: subdomen qöşiladi, unga bepul Let's Encrypt sertifikati ulanadi va sertifikat muddati tugaşidan oldin avtomatik yangilanadi. Sertifikat yangilanmay qolsa, Mini App foydalanuvçilarda oq ekran bilan oçiladi, şuning uçun avtomatik yangilaniş bu yerda juda muhim.
Frontendni build qilgaç, dist papkasidagi fayllarni subdomenning ildiz katalogiga yuklang. Agar ilova klient tomonida marşrutlaşdan foydalansa, barça noma'lum manzillarni index.html fayliga yönaltiriş kerak. Apaçe işlatiladigan hostingda buni .htaccess fayli bilan qiliş mumkin:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/api/
RewriteRule ^ index.html [L]
Frontend: telegram-web-app.js bilan işlaş
Telegram bilan aloqa rasmiy skript orqali örnatiladi. U sahifaga window.Telegram.WebApp obyektini qöşadi. ready() metodi Telegram'ga ilova yuklanganini bildiradi, expand() esa oynani töliq balandlikka oçadi. Pastdagi asosiy tugma MainButton orqali boşqariladi va u Telegram dizayniga mos körinadi.
<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>
Ilova ranglarini qölda tanlaş örniga tg.themeParams qiymatlaridan foydalaniş tavsiya etiladi. Şunda Mini App foydalanuvçining kunduzgi yoki tungi mavzusiga moslaşadi va Telegram içida begonadek körinmaydi.
Eng muhim qism: initData'ni serverda tekşiriş
Frontend foydalanuvçi haqidagi ma'lumotni ikki körinişda oladi: initDataUnsafe obyekti va initData satri. Nomidan ham körinib turibdiki, birinçisiga işonib bölmaydi, çunki brauzerdagi istalgan qiymatni soxtalaştiriş mumkin. Töğri yöl initData satrini serverga yuborib, uning imzosini bot tokeni yordamida tekşirişdir. Telegram hujjatlariga köra kalit WebAppData sözi va bot tokenidan HMAC-SHA256 orqali hosil qilinadi, söng saralangan maydonlar satri şu kalit bilan imzolanadi.
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;
}
Funksiya imzo töğri bölsa maydonlar massivini qaytaradi, user maydoni esa JSON körinişida bölib, uni json_decode bilan öqiş mumkin. auth_date tekşiruvi eski, uşlab qolingan sörovlarni qayta işlatişdan himoya qiladi. Bot tokeni faqat serverda, masalan veb-katalogdan taşqaridagi konfiguratsiya faylida saqlanişi kerak.
BotFather orqali botga ulaş
Ilova tayyor bölgaç, uni botga boğlaş qoladi. Buning bir neçta usuli bor va ularni birgalikda işlatiş ham mumkin:
- Menyu tugmasi: BotFather'da bot sozlamalaridan menyu tugmasini sozlab, unga
https://app.misol.uzmanzilini berasiz. - Töğridan-töğri havola:
/newappbuyruği bilan ilova yaratib, uni alohida havola orqali ulaşiş mumkin. - Klaviatura tugmasi: bot xabarida
web_appturidagi tugma yuborib, ilovani muayyan suhbat içidan oçiş mumkin.
Sinov paytida Telegram içki brauzeri sahifani keşlab qolişi mumkin, şuning uçun yangi build yuklagandan keyin fayl nomlarida hash bölişiga e'tibor bering; Vite va boşqa zamonaviy yiğuvçilar buni avtomatik bajaradi. Xatolarni topiş uçun Telegram Desktop yoki Android ilovasidagi veb-tekşiruv imkoniyatlari haqida rasmiy hujjatlarni körib çiqing.