Telegram Usługi i architektura tworzenia miniaplikacji: co to jest i jak ją zbudować

Miniaplikacja Telegram nie jest botem z ładniejszymi przyciskami. Jest to prawdziwa aplikacja internetowa - HTML, CSS, JavaScript – którą Telegram otwiera się w arkuszu wewnątrz czatu. Użytkownik nigdy nie opuszcza komunikatora, nigdy nie odwiedza sklepu z aplikacjami i często nigdy nie wpisuje hasła. Oto produkt: wykonana praca tam, gdzie już toczy się rozmowa.

Ludzie nadal mówią „Telegram aplikacja internetowa”, ponieważ taka była stara nazwa. To samo: strona HTTPS, pakiet SDK aplikacji internetowej i bot, który ją otwiera. Jeśli wkleisz witrynę marketingową do tego widoku, nie masz aplikacji Mini. Masz ciasną witrynę z nagłówkiem Telegram. W tym artykule opisano, jak faktycznie potraktowałbym powierzchnię.

1. Miniaplikacja vs bot vs strona internetowa vs aplikacja sklepowa

Te cztery powierzchnie rozwiązują różne zadania. Mieszając je, otrzymasz bota, który próbuje być sklepem lub miniaplikacją, która próbuje uzyskać pozycję w Google.

• Bot: interfejs czatu. Świetnie nadaje się do poleceń, alertów i płatności jednorazowych. „Wyślij mi ten plik PDF”. Straszne dla katalogów, kalendarzy i formularzy wieloetapowych.
• Witryna internetowa: publiczny adres URL, SEO, linki do udostępniania, pulpit. Drzwi wejściowe dla osób, które nie są jeszcze w Twojej Telegram.
• Aplikacja Store: instalacja, push, offline, podatek App Store. Właśnie wtedy, gdy potrzebujesz uprawnień systemu operacyjnego. Źle, gdy praca polega na „zarezerwowaniu miejsca w 40 sekund”.
• Mini App: pełny interfejs użytkownika w Telegram, tożsamość na czacie, płatności gwiazdkami lub fakturami, aktualizacje bez sprawdzania sklepu. Produkt żyje tam, gdzie klient już z Tobą rozmawia.

2. Jak to jest faktycznie podłączone

Trzy sztuki, nie jedna. Jeśli przegapisz którykolwiek z nich, otrzymasz wersję demonstracyjną, a nie produkt.

• Bot. Jest właścicielem przycisku menu, aplikacji internetowej KeyboardButton, przycisku wbudowanego lub bezpośredniego łącza (t.me/bot/app). Bez bota nie ma co otwierać arkusza.
• Aplikacja internetowa HTTPS. Telegram ładuje Twój adres URL w przeglądarce internetowej. Next.js na Vercel (lub dowolnym hoście HTTPS) jest w porządku. Sztuczki HTTP i localhost są tylko w fazie rozwoju.
• Zestaw SDK aplikacji internetowej („window.Telegram.WebApp`). Motyw, rzutnia, MainButton, BackButton, haptic, CloudStorage, faktura, obiekt użytkownika. Bez tego zgadujesz CSS w ciemności.

3. Tożsamość: initData nie jest ekranem logowania

Gdy Telegram otwiera Twoją stronę, dołącza podpisane `initData`: identyfikator użytkownika, imię i nazwisko, język, opcjonalne zapytanie, skrót. Taka jest sesja. Użytkownik udowodnił już, że jest właścicielem tego konta Telegram, będąc w aplikacji. Nie włączaj opcji „zaloguj się za pomocą poczty e-mail”, chyba że musisz powiązać istniejącą szafkę.

Nigdy nie ufaj `initData` w przeglądarce. Każdy może otworzyć DevTools i sfałszować obiekt użytkownika. Serwer musi zweryfikować skrót za pomocą HMAC za pomocą tokena bota, sprawdzić, czy wartość „data_auth” jest świeża, a następnie utworzyć własny plik cookie sesji lub JWT. Jeśli pominiesz ten krok, nie masz autoryzacji. Masz kostium.

4. UX, który nie przypomina witryny w szufladzie

Telegram ma już chrom: uchwyt, bezpieczne obszary, motyw podążający za światłem/ciemnością. Walcz z tym, a aplikacja będzie wydawać się obca. Użyj go, a poczujesz się natywny.

• MainButton to podstawowa akcja - zapłać, zarezerwuj, wyślij. Przycisk CSS na dole będzie znajdował się pod wskaźnikiem strony głównej i będzie wyglądał jak klon.
• Przycisk Wstecz dla zagnieżdżonych ekranów. Przesunięcie Telegram w dół powoduje zamknięcie aplikacji Mini – nie kradnij tego gestu w przypadku „poprzedniego kroku”.
• Przeczytaj `themeParams` i `colorScheme`. Zakodowane na stałe białe strony w ciemnym Telegramie wyglądają jak błąd.
• Widok nie jest „100vh”. Użyj `viewportStableHeight` i rozwiń, gdy potrzebujesz pełnego arkusza. Przetestuj na iOS i Androidzie - nie zgadzają się.

5. Kiedy faktycznie wyślę Mini Aplikację

Zbudowałbym taki, gdy klient jest już w Telegram – lub będzie, bo tak się mówi w tym biznesie – a zadanie wymaga prawdziwego interfejsu użytkownika, a nie łańcucha komunikatów.

• Rezerwacja za pomocą kalendarza, a nie „odpowiadanie datą”. Sklepy z filtrami. Szafki kursowe. Kalkulatory, które stają się leadem. Karty lojalnościowe. Narzędzia wewnętrzne dla zespołu, który już żyje w grupie.
• Płatności, które nie powinny opuszczać czatu: Telegram gwiazdek, faktury lub już uruchomiona kasa - otwarta z poziomu aplikacji Mini, ponownie potwierdzona w bocie.

6. Kiedy odmówiłem

Miniaplikacja nie zastępuje strony internetowej. To nie ma rangi. Nie sprawdza się jako jedyne drzwi, jeśli połowa kupujących przyjeżdża z Google. To także złe miejsce na porzucenie CRM na komputer.

• SEO, blog, katalog publiczny, „o nas”, strony rekrutacyjne – czyli strona internetowa. Stamtąd link do aplikacji Mini, jeśli praca będzie kontynuowana na czacie.
• Ciężka grafika, ogromne stoły, administrator z wieloma oknami. Arkusz jest powierzchnią, na którą zwraca się uwagę telefonem. Zbuduj prawdziwego administratora w sieci.
• Jeśli jedynym wymaganiem jest to, że „słyszeliśmy, że Mini Apps cieszą się popularnością” i nie ma Telegram odbiorców – zacznij od witryny i bota, który wykonuje jedno zadanie.

7. Stos, z którym otworzyłbym w 2026 roku

Taka sama dyscyplina jak MVP: jeden kod, który później może być także stroną internetową, nudna baza danych, bot, który tylko otwiera drzwi i potwierdza płatności.

• Next.js + TypeScript + Wiatr w interfejsie użytkownika. Jedna aplikacja: trasy Mini App i, w razie potrzeby, publiczna witryna marketingowa.
• PostgreSQL jako źródło prawdy. Użytkownicy wpisani za pomocą Telegram identyfikatora. Redis, jeśli potrzebujesz limitów stawek lub krótkotrwałych wersji roboczych.
• Mały bot (grammY lub Telegraf) do obsługi przycisku Menu, faktur i wiadomości po dokonaniu płatności. Nie umieszczaj logiki biznesowej tylko w bocie, jeśli Mini App również tego potrzebuje - udostępnij moduł.
• Sprawdź poprawność initData na serwerze przy każdym uprzywilejowanym żądaniu. Nie przechowuj niczego tajnego w widoku internetowym.

Mini App to drzwi, a nie marka

Traktuj to jak powierzchnię produktu z umową: otwórz szybko, wyglądaj jak Telegram, udowodnij użytkownika na serwerze, zakończ jedno zlecenie, wyślij paragon z powrotem na czat. Jeśli potrzebujesz odkryć, SEO i historii dla nieznajomych – to wciąż jest strona internetowa. Jeśli potrzebujesz rozmowy i prawdziwego interfejsu użytkownika - jest to Mini App. Drugi wysłałbym, gdy publiczność jest już w komunikatorze. Nie wysłałbym tego, ponieważ stara nazwa „Aplikacja internetowa” brzmiała taniej niż wersja App Store.