Telegram Servicii și arhitectură de dezvoltare pentru mini aplicații: ce este și cum să construiți una

O aplicație Telegram Mini nu este un bot cu butoane mai frumoase. Este o adevărată aplicație web - HTML, CSS, JavaScript - care Telegram se deschide într-o foaie în interiorul chat-ului. Utilizatorul nu părăsește niciodată messengerul, nu vizitează niciodată un magazin de aplicații și, adesea, nu introduce niciodată o parolă. Acesta este produsul: o treabă făcută acolo unde este deja conversația.

Oamenii încă spun „Telegram Web App” pentru că acesta era numele vechi. Același lucru: o pagină HTTPS plus SDK-ul WebApp plus un bot care o deschide. Dacă inserați un site de marketing în acea vizualizare web, nu aveți o aplicație mini. Aveți un site web înghesuit cu un antet Telegram. Acest articol este modul în care aș trata de fapt suprafața.

1. Mini aplicație vs bot vs site web vs aplicație magazin

Aceste patru suprafețe rezolvă sarcini diferite. Combinând-le, obțineți un bot care încearcă să fie un magazin sau o mini-aplicație care încearcă să se claseze pe Google.

• Bot: interfață de chat. Excelent pentru comenzi, alerte, plăți unice, „trimite-mi acest PDF”. Teribil pentru cataloage, calendare și formulare cu mai mulți pași.
• Site: URL public, SEO, linkuri care pot fi partajate, desktop. Ușa din față pentru persoanele care nu sunt deja în Telegram.
• Aplicația magazin: instalare, push, offline, taxă App Store. Chiar atunci când aveți nevoie de privilegii OS. Greșit când jobul este „rezerva un slot în 40 de secunde”.
• Mini App: interfață de utilizare completă în Telegram, identitate din chat, plăți prin Stars sau facturi, actualizări fără o revizuire a magazinului. Produsul locuiește acolo unde clientul discută deja cu dvs.

2. Cum este de fapt conectat

Trei piese, nu una. Pierdeți oricare dintre ele și aveți un demo, nu un produs.

• Un bot. Deține butonul de meniu, KeyboardButton web_app, butonul inline sau linkul direct (t.me/bot/app). Fără un bot nu există nimic care să deschidă foaia.
• O aplicație web HTTPS. Telegram încarcă adresa URL într-o vizualizare web. Next.js pe Vercel (sau orice gazdă HTTPS) este în regulă. Trucurile HTTP și localhost aparțin numai dezvoltării.
• SDK-ul WebApp (`window.Telegram.WebApp`). Tema, viewport, MainButton, BackButton, haptic, CloudStorage, factura, obiectul utilizatorului. Fără el, ghiciți CSS în întuneric.

3. Identitate: initData nu este un ecran de conectare

Când Telegram deschide pagina dvs., se adaugă `initData` semnat: ID utilizator, nume, limbă, interogare opțională, un hash. Asta este sesiunea. Utilizatorul a dovedit deja că deține acel cont Telegram fiind în interiorul aplicației. Nu fixați „conectați-vă cu e-mail” decât dacă trebuie să legați un cabinet existent.

Nu aveți încredere niciodată în `initData` în browser. Oricine poate deschide DevTools și poate falsifica un obiect utilizator. Serverul trebuie să valideze HMAC hash-ul cu simbolul bot, să verifice că `auth_date` este proaspăt, apoi să creeze propriul cookie de sesiune sau JWT. Dacă săriți peste acel pas, nu aveți auth. Ai un costum.

4. UX care nu se simte ca un site web într-un sertar

Telegram are deja crom: un mâner de prindere, zone sigure, o temă care urmează lumina/întuneric. Luptă-te și aplicația se simte străină. Folosește-l și te simți nativ.

• MainButton este acțiunea principală - plătiți, rezervați, trimiteți. Un buton CSS din partea de jos va sta sub indicatorul de pornire și va arăta ca o clonă.
• BackButton pentru ecrane imbricate. Glisarea Telegram în jos închide aplicația Mini - nu fura acel gest pentru „pasul anterior”.
• Citiți `themeParams` și `colorScheme`. Paginile albe codificate tare în Telegram întunecate arată ca un bug.
• Viewport nu este `100vh`. Utilizați `viewportStableHeight` și extindeți când aveți nevoie de foaia completă. Testați pe iOS și Android - nu sunt de acord.

5. Când aș expedia de fapt o Mini App

Aș construi unul când clientul este deja în Telegram - sau va fi, pentru că așa vorbește această afacere - și jobul are nevoie de o interfață reală, nu de un lanț de mesaje.

• Rezervați cu un calendar, nu „răspundeți cu o dată”. Magazine cu filtre. Cabinete de curs. Calculatoare care devin lider. Carduri de fidelitate. Instrumente interne pentru o echipă care trăiește deja într-un grup.
• Plăți care nu ar trebui să părăsească chatul: Telegram stele, facturi sau o casă pe care o rulați deja - deschise din Mini App, confirmate din nou în bot.

6. Când aș refuza

O mini-aplicație nu înlocuiește un site web. Nu se clasează. Nu funcționează bine ca singura ușă dacă jumătate dintre cumpărători ajung de la Google. Este, de asemenea, un loc prost pentru a arunca un desktop CRM.

• SEO, blog, catalog public, „despre noi”, pagini de angajare - adică un site web. Conectați-vă la Mini App de acolo dacă lucrarea continuă în chat.
• Grafică grea, tabele uriașe, administrator cu mai multe ferestre. Foaia este o suprafață pe primul loc pentru telefon. Creați un adevărat administrator pe web.
• Dacă singura cerință este „am auzit că Mini Apps sunt în tendințe” și nu există Telegram audiență - începeți cu un site și un bot care face o singură treabă.

7. Stiva cu care aș deschide în 2026

Aceeași disciplină ca un MVP: o bază de cod care poate fi și site-ul mai târziu, o bază de date plictisitoare, un bot care doar deschide ușa și confirmă plățile.

• Next.js + TypeScript + Tailwind pentru UI. O aplicație: rute pentru Mini App și, dacă este necesar, site-ul de marketing public.
• PostgreSQL ca sursă a adevărului. Utilizatori tastați de Telegram id. Redis dacă aveți nevoie de limite de rată sau de proiecte de scurtă durată.
• Un bot mic (grammY sau Telegraf) pentru butonul de meniu, facturi și mesaje ulterioare plății. Nu puneți logica de afaceri doar în bot dacă și Mini App are nevoie de ea - partajați un modul.
• Validați initData pe server pentru fiecare solicitare privilegiată. Nu stocați nimic secret în vizualizarea web.

Aplicația Mini este o ușă, nu o marcă

Tratați-o ca pe o suprafață de produs cu un contract: deschideți rapid, arătați ca Telegram, dovediți utilizatorul pe server, finalizați o lucrare, trimiteți chitanța înapoi în chat. Dacă aveți nevoie de descoperire, SEO și o poveste pentru străini - acesta este încă un site web. Dacă aveți nevoie de o conversație plus o interfață de utilizare reală - aceasta este o aplicație Mini. Aș expedia al doilea atunci când publicul este deja în messenger. Nu l-aș trimite pentru că vechiul nume „Web App” suna mai ieftin decât o versiune App Store.