Telegram Mini App’ni qanday test qilish va debug qilish mumkin

Qisqacha

Mini App — Telegram WebView ichida ishlaydigan veb-sahifa. Debug qilish to‘rtta odatga borib taqaladi:

1. Ilovani lokal ishga tushiring va uni HTTPS tunnel orqali oching.
2. Shu manzilga alohida dev botni ulang, toki real foydalanuvchilar chala ishni ko‘rmasin.
3. Interfeys ustidagi kundalik ish uchun oddiy brauzerda Telegram muhitini mock qiling.
4. Relizdan oldin ilovani WebView devtools yoqilgan barcha mijozlarda oching.

HTTPS tunnel orqali lokal ishga tushirish

Telegram Mini App’ni HTTPS orqali ochadi, shuning uchun ilova ichida oddiy localhost ishlamaydi.

1. Dev serverni ishga tushiring, masalan 5173-portda.
2. Tunnel oching: cloudflared tunnel --url http://localhost:5173 yoki ngrok http 5173.
3. @BotFather’da dev botingizning Mini App’i yoki menyu tugmasi uchun tunnel manzilini ko‘rsating.
4. Telegram’da botni oching va ilovani ishga tushiring.

Odatiy muammolar:

• Ba’zi dev serverlar, jumladan Vite, notanish hostlardan kelgan so‘rovlarni rad etadi. Tunnel domenini ruxsat etilgan hostlarga qo‘shing.
• Hot reload tunnel orqali ishlashi uchun WebSocket sozlamalarini o‘zgartirish kerak bo‘lishi mumkin.
• Bepul tunnellar ko‘pincha har qayta ishga tushirishda manzilni o‘zgartiradi va uni BotFather’da yangilashga to‘g‘ri keladi. Zaxiralangan domen bu qadamdan xalos qiladi.

Telegram test muhiti

Telegram’da o‘z akkauntlari, botlari va ma’lumotlariga ega alohida test serveri bor. U to‘liq izolyatsiya kerak bo‘lganda foydali, masalan production’ga tegmasdan to‘lovlarni tekshirish uchun.

• iOS: sozlamalar belgisini 10 marta bosing, Accounts bo‘limini oching, Login to another account’ni, so‘ng Test’ni tanlang.
• Telegram Desktop: sozlamalarni oching, Shift + Alt tugmalarini bosib turib Add Account’ga o‘ng tugma bilan bosing, so‘ng Test Server’ni tanlang.
• Test muhiti ichida @BotFather orqali bot yarating. Shunda Bot API so‘rovlari https://api.telegram.org/bot<token>/test/METHOD manziliga yuboriladi.
• Test muhitida TLS’siz Mini App havolalariga ruxsat beriladi, bu lokal ishni osonlashtiradi.

Ko‘pchilik loyihalar uchun oddiy muhitdagi dev bot yetarli; test serveri majburiy talab emas, balki qo‘shimcha qatlam.

WebView debug’ni yoqish

Menyu bandlari nomlari mijoz versiyalari orasida o‘zgarishi mumkin — dolzarb qadamlar Mini Apps rasmiy hujjatlarida bor. Zaxira variant sifatida faqat dev build’larda ulanadigan sahifa ichidagi konsol, masalan Eruda, mos keladi: u loglarni to‘g‘ridan-to‘g‘ri telefonda ko‘rsatadi.

initData va mavzu parametrlarini mock qilish

Oddiy brauzerda window.Telegram.WebAppda initData, foydalanuvchi va mavzu yo‘q. Ularni faqat ishlab chiqishda mock qiling:

const tg = (window as any).Telegram?.WebApp;

if (import.meta.env.DEV && !tg?.initData) {
  const theme = {
    bg_color: "#ffffff",
    text_color: "#000000",
    button_color: "#2481cc",
    button_text_color: "#ffffff",
  };
  for (const [key, value] of Object.entries(theme)) {
    document.documentElement.style.setProperty(
      `--tg-theme-${key.replace(/_/g, "-")}`,
      value,
    );
  }
}

@telegram-apps/sdk kabi kutubxonalar foydalanuvchi va start parametrlari bilan birga butun ishga tushirish muhitini mock qiladigan yordamchi funksiyalarni taklif qiladi.

Backend bilan murakkabroq: u initDatani bot tokeniga asoslangan HMAC imzosi bo‘yicha tekshiradi. Ikki xavfsiz variant bor: testlarda test initDatani dev bot tokeni bilan o‘zingiz imzolang yoki production’da yoqib bo‘lmaydigan, belgilangan test foydalanuvchili faqat ishlab chiqish uchun aylanib o‘tish yo‘lini qo‘shing.

Qorong‘i mavzu mock’ini ham saqlang: ko‘plab maket xatolari faqat ranglar almashganda yuzaga chiqadi.

Turli mijozlarda xatti-harakatni tekshirish

• Viewport: klaviatura ochilganda ko‘rinadigan balandlik o‘zgaradi — ekran pastidagi formalarni tekshiring.
• Kesikli telefonlarda xavfsiz hududlar va to‘liq ekran rejimi.
• MainButton va BackButton: har bir ekranda ko‘rinishi, matni va handler’lari.
• Ilova ochiq turganda themeChanged hodisasi orqali mavzu almashishi.
• Havolalar: tashqi sahifalar openLink orqali, Telegram havolalari openTelegramLink orqali.
• Eski mijozlar: yangi metodlarni isVersionAtLeast tekshiruvi bilan o‘rang.
• Android, iOS, Desktop, macOS va Telegram Web — kichik ekranda va sekin tarmoqda.