Telegram Mini App aslında nedir - ve ben ne zaman bir tane kurardım

Telegram Mini App, daha güzel düğmeli bir bot değildir. Telegram’ın sohbet içinde bir panelde açtığı gerçek bir web uygulamasıdır - HTML, CSS, JavaScript. Kullanıcı messenger’dan çıkmaz, app store’a gitmez ve çoğu zaman şifre yazmaz. Ürün budur: görev, konuşmanın zaten olduğu yerde biter.

Hâlâ «Telegram Web App» diyenler var - eski ad. Aynı şey: bir HTTPS sayfa artı WebApp SDK artı onu açan bir bot. Pazarlama sitesini o webview’a yapıştırmak Mini App değildir. Telegram başlıklı sıkışmış bir sitedir. Bu yazı, o yüzeyi gerçekten nasıl ele alırdım.

1. Mini App, bot, site ve store uygulaması

Bu dört yüzey farklı görevler çözer. Karıştırmak, dükkân olmaya çalışan bir bot veya Google’da görünmek isteyen bir Mini App üretir.

• Bot: sohbet arayüzü. Komut, uyarı, tek seferlik ödeme, «şu PDF’i gönder» için iyi. Katalog, takvim ve çok adımlı form için kötü.
• Site: herkese açık URL, SEO, paylaşılabilir bağlantı, masaüstü. Telegram’ınızda henüz olmayanlar için kapı.
• Store uygulaması: kurulum, push, çevrimdışı, Apple/Google vergisi. OS ayrıcalığı gerektiğinde doğru. Görev «40 saniyede slot ayırt» ise yanlış.
• Mini App: Telegram içinde tam arayüz, sohbetten kimlik, Stars veya fatura ile ödeme, store incelemesi olmadan güncelleme. Ürün, müşterinin zaten yazıştığı yerde yaşar.

2. Gerçekten nasıl kurulur

Üç parça, bir değil. Birini atlayın - demo olur, ürün olmaz.

• Bir bot. Menü düğmesi, KeyboardButton web_app, inline düğme veya doğrudan bağlantı (t.me/bot/app) onda durur. Bot yoksa paneli açacak bir şey yoktur.
• Bir HTTPS web uygulaması. Telegram URL’nizi bir webview’da yükler. Vercel’de Next.js (veya herhangi bir HTTPS host) yeter. HTTP ve localhost numaraları yalnızca geliştirmede.
• WebApp SDK (`window.Telegram.WebApp`). Tema, viewport, MainButton, BackButton, haptic, CloudStorage, fatura, kullanıcı nesnesi. O olmadan CSS’i karanlıkta tahmin edersiniz.

3. Kimlik: initData bir giriş ekranı değildir

Telegram sayfanızı açınca imzalı `initData` ekler: kullanıcı id, ad, dil, isteğe bağlı query, hash. Oturum budur. Kullanıcı o Telegram hesabına sahip olduğunu zaten kanıtladı - uygulamanın içinde. Mevcut bir müşteri hesabını bağlamanız gerekmiyorsa «e-posta ile giriş» eklemeyin.

Tarayıcıdaki `initData`’ya asla güvenmeyin. Herkes DevTools açıp sahte bir kullanıcı nesnesi yazar. Sunucu bot token ile HMAC hash’i doğrulamalı, `auth_date`’in taze olduğunu kontrol etmeli, sonra sizin oturum çerezini veya JWT’yi basmalıdır. O adımı atlarsanız kimlik doğrulamanız yoktur. Bir kostümünüz vardır.

4. Çekmecede site gibi durmayan UX

Telegram’ın zaten kendi arayüzü var: tutacak, safe area, açık/koyu tema. Onunla savaşın, uygulama yabancı durur. Kullanın, native durur.

• MainButton birincil eylemdir - öde, ayırt, gönder. Alttaki bir CSS düğmesi home göstergesinin altına oturur ve klon gibi durur.
• İç içe ekranlar için BackButton. Telegram’da aşağı kaydırma Mini App’i kapatır - o jesti «önceki adım» için çalmayın.
• `themeParams` ve `colorScheme` okuyun. Koyu Telegram’da sabit beyaz sayfa hata gibi durur.
• Viewport `100vh` değildir. Tam panel gerektiğinde `viewportStableHeight` ve expand kullanın. iOS ve Android’de test edin - anlaşmazlar.

5. Mini App’i gerçekten ne zaman canlıya alırdım

Müşteri zaten Telegram’daysa - veya olacaksa, çünkü bu iş öyle konuşuyor - ve görev bir mesaj zinciri değil gerçek bir arayüz istiyorsa Mini App kurardım.

• Tarihle cevap değil, takvimle rezervasyon. Filtreli dükkânlar. Kurs hesapları. Talebe dönüşen hesaplayıcılar. Sadakat kartları. Zaten bir grupta yaşayan ekip için iç araçlar.
• Sohbetten çıkmaması gereken ödeme: Telegram Stars, fatura, veya zaten işlettiğiniz checkout - Mini App’ten açılır, botta onaylanır.

6. Ne zaman reddederdim

Mini App bir sitenin yerini tutmaz. Aramada görünmez. Alıcıların yarısı Google’dan geliyorsa tek kapı olarak kötü durur. Masaüstü CRM dökmek için de kötü bir yerdir.

• SEO, blog, herkese açık katalog, «hakkımızda», iş ilanları - o bir sitedir. Görev sohbette devam ediyorsa oradan Mini App’e bağlantı verin.
• Ağır grafik, kocaman tablolar, çok pencereli admin. Panel telefon-öncelikli bir yüzeydir. Asıl admin’i web’de kurun.
• Tek gereksinim «Mini App trendmiş» ise ve Telegram kitlesi yoksa - bir site ve tek görev yapan bir bot ile başlayın.

7. 2026’da açacağım stack

MVP ile aynı disiplin: sonra site de olabilecek tek bir kod tabanı, sıkıcı bir veritabanı, yalnızca kapıyı açıp ödemeleri onaylayan bir bot.

• Arayüz için Next.js + TypeScript + Tailwind. Tek uygulama: Mini App route’ları ve gerekirse herkese açık pazarlama sitesi.
• Asıl kayıt olarak PostgreSQL. Kullanıcılar Telegram id anahtarıyla. Rate limit veya kısa taslak varsa Redis.
• Menu Button, fatura ve ödeme sonrası mesajlar için küçük bir bot (grammY veya Telegraf). Mini App de ona ihtiyaç duyuyorsa iş mantığını yalnızca botta tutmayın - ortak bir modül.
• Her ayrıcalıklı istekte initData’yı sunucuda doğrulayın. Webview’da sır saklamayın.

Mini App bir kapıdır, marka değil

Onu sözleşmeli bir ürün yüzeyi gibi ele alın: hızlı açılsın, Telegram gibi dursun, kullanıcıyı sunucuda kanıtlasın, bir görevi bitsin, makbuzu sohbete geri göndersin. Keşif, SEO ve yabancılar için bir hikâye gerekiyorsa - o hâlâ bir sitedir. Konuşma artı gerçek bir arayüz gerekiyorsa - o bir Mini App’tir. Kitle zaten messenger’daysa ikincisini canlıya alırdım. Eski ad «Web App» App Store derlemesinden ucuz diye değil.