Telegram Ekosisteminde Mini Uygulamaları Başlatma ve Oluşturma

Telegram'da bir mini uygulamayı (Mini App) bağlamak ve başlatmak için, normal bir kullanıcının ilgili botu veya bağlantıyı bulup "Başlat" (Open) düğmesine tıklaması yeterlidir; ayrı dosyaların kurulması gerekmez. Geliştirici için bağlantı süreci, @BotFather aracılığıyla bir bot oluşturmak, projenin web sürümünü HTTPS barındırma hizmetinde yayınlamak ve bot ayarlarında alan adını ilişkilendirmekten ibarettir. Tüm entegrasyon, WebView teknolojisi aracılığıyla mesajlaşma uygulamasının arayüzü içinde gerçekleşir.

Telegram Mini Apps Nedir ve Neden Gereklidir?

Mini uygulamalar, bir botla sohbet penceresinde veya bir bağlantı üzerinden doğrudan açılan tam teşekküllü web hizmetleridir (HTML5 tabanlı). Akıllı telefonun hafızasında yer kaplamazlar, tüm platformlarda (iOS, Android, Masaüstü) çalışırlar ve kullanıcı profil verilerine (kullanıcının izniyle) erişimleri vardır.

Normal web sitelerinden farklı olarak, mini uygulamalar Telegram'ın yerel arayüzünü kullanır: koyu/açık tema otomatik olarak uyum sağlar ve gezinme mobil cihazlar için uyarlanmıştır. 2026 yılında bu format, mesajlaşma uygulaması içindeki kripto oyunları, çevrimiçi mağazalar, teslimat hizmetleri ve bankacılık işlemleri için standart haline gelmiştir.

Kullanıcı Talimatları: Mini Uygulama Nasıl Açılır?

Son kullanıcı için süreç son derece basitleştirilmiştir ve teknik beceri gerektirmez.

1. Hizmeti Arama. Telegram arama özelliği aracılığıyla hizmetin resmi botunu bulun (örneğin, yemek siparişi için @DurgerKingBot veya @Notcoin_bot gibi oyun botları). Ayrıca, proje kanallarında sıkça bağlantılar yayınlanır.
2. Başlatma. Bot ile sohbet ekranının alt kısmında özel bir menü düğmesi görünecektir (genellikle "Menu", "Launch App" veya "Başlat" olarak adlandırılır). Buna tıklayın.
3. Kimlik Doğrulama. İlk başlatmada uygulama, adınıza ve profil fotoğrafınıza erişim izni isteyecektir. "İzin Ver"e tıklayarak işlemi onaylayın.
4. Kullanım. Uygulama arayüzü tam ekrana genişleyecektir. Mesajlaşma uygulamasından çıkmadan alışveriş yapabilir, oyun oynayabilir veya ayarları yönetebilirsiniz.

Düğme görünmüyorsa veya uygulama yüklenmiyorsa:

• Güncel Telegram sürümünün yüklü olduğundan emin olun (App Store veya Google Play'de güncellemeleri kontrol edin).
• İnternet bağlantınızı kontrol edin. Bazı bölgelerde, yerleşik tarayıcının çalışması için kararlı bir bağlantı veya ağ ayarları gerekebilir.

Geliştirici İçin Adım Adım Talimatlar: Oluşturma ve Bağlama

Kendi mini uygulamanızı geliştirme ve bağlama süreci, işlevselliğin karmaşıklığına bağlı olarak 30 dakikadan birkaç saate kadar sürebilir.

Adım 1: Bot Kaydı

Her şey bir kabuk bot oluşturmakla başlar.

1. Resmi bot @BotFather ile sohbeti açın.
2. /newbot komutunu gönderin.
3. Bir isim (sohbet listesinde görüntülenir) ve bir kullanıcı adı düşünün (bot ile bitmelidir, örneğin my_super_app_bot).
4. Verilen API token'ını kaydedin. Projenizin sunucu tarafı için buna ihtiyacınız olacak.

Adım 2: Web Uygulamasını Hazırlama

Mobil cihazlar için uyarlanmış çalışan bir web sitesine ihtiyacınız var.

1. Proje dosyalarını (HTML, CSS, JS) HTTPS destekli herhangi bir barındırma hizmetine yerleştirin (Vercel, Netlify, GitHub Pages mükemmel şekilde uygundur). Ücretsiz planlar genellikle başlangıç için yeterlidir.
2. Telegram WebApp betiğini index.html dosyanızın <head> bölümüne ekleyin:

    <script src="https://telegram.org/js/telegram-web-app.js"></script>
    ```
3.  Uygulamayı JavaScript'te başlatın:
    
```javascript
    const tg = window.Telegram.WebApp;
    tg.ready();
    // Tam ekrana genişletme örneği
    tg.expand(); 
    ```

Adım 3: Uygulamayı Bota Bağlama

Şimdi oluşturulan siteyi @BotFather aracılığıyla botla ilişkilendirmeniz gerekiyor.

1. /mybots komutunu girin ve botunuzu seçin.
2. Bot Settings → Menu Button bölümüne gidin.
3. Configure Menu Button seçeneğini seçin.
4. BotFather sizden bir bağlantı göndermenizi isteyecektir. Uygulamanızın tam URL'sini gönderin (örneğin, https://my-app.vercel.app).
5. Kullanıcıların göreceği düğme adını girin (örneğin, "Mağazayı Aç").

Bundan sonra, botunuzun sohbetini açan tüm kullanıcıların metin giriş alanının solunda uygulamayı başlatma düğmesi görünecektir.

Adım 4: Ek İşlevlerin Yapılandırılması (İsteğe Bağlı)

Yetenekleri genişletmek için @BotFather'daki komutları veya API'yi kullanın:

• Ödemeler: Sağlayıcıları (Stripe, ЮKassa vb.) bağlamak için /setpayments aracılığıyla yapılandırın.
• Satır İçi Mod: Uygulamanın herhangi bir sohbetteki mesaj giriş alanında doğrudan başlatılmasına olanak tanır (/setinline komutu).
• Derin Bağlantı (Deep linking): Başlatma parametrelerini (örneğin, yönlendirme kodu) aktarmak için t.me/yourbot/app?startapp=param biçimindeki bağlantıları kullanın.

Entegrasyon Yöntemlerinin Karşılaştırılması

Sık Karşılaşılan Hatalar ve Çözüm Yolları

Doğru yapılandırmaya rağmen teknik nüanslar ortaya çıkabilir. İşte en yaygın sorunlar:

• "Uygulama yüklenmiyor" (beyaz ekran).

  • Neden: Çoğunlukla sorun karışık içerikten (HTTPS sitesi HTTP üzerinden kaynak yüklemeye çalışıyor) veya alan adının engellenmesinden kaynaklanır.
  • Çözüm: Tarayıcıdaki geliştirici konsolunu kontrol edin, tüm kaynakların güvenli protokol üzerinden yüklendiğinden emin olun. Telegram önbelleğini temizleyin (Ayarlar → Veriler ve Depolama → Önbelleği Temizle).

• Veri başlatma hatası (initData undefined).

  • Neden: Betik, Telegram arayüzü tamamen yüklenmeden önce kullanıcı verilerini okumaya çalışıyor.
  • Çözüm: Verilerle çalışma mantığını tg.onEvent('mainButtonClicked', ...) olayına sarın veya çağrının tg.ready() sonrasında yapıldığından emin olun.

• Menü düğmesi kullanıcılarda görünmüyor.

  • Neden: Kullanıcı çok eski bir istemci sürümü kullanıyor veya BotFather'daki ayar bozulmuş.
  • Çözüm: Kullanıcıdan uygulamayı güncellemesini isteyin. /mybots aracılığıyla düğme ayarlarını tekrar kontrol edin.

SSS

Her hizmet için ayrı bir uygulama indirmem gerekiyor mu? Hayır. Tüm mini uygulamalar ana Telegram uygulaması içinde çalışır. Cihazda ayrı simgeler olarak kurulmazlar (Telegram içindeki tarayıcı menüsü aracılığıyla ana ekrana kısayol ekleme seçeneği hariç).

Mini uygulamada kart bilgilerini girmek güvenli mi? Evet, hizmet resmi Telegram ödeme ağ geçidini veya güvenilir sağlayıcıları kullanıyorsa güvenlidir. Veriler güvenli bir kanal üzerinden iletilir. Botun doğrulama işaretine sahip olduğundan veya çok sayıda olumlu incelemesi bulunduğundan her zaman emin olun.

Programlama bilgisi olmadan mini uygulama oluşturabilir miyim? Basit bir mini uygulamayı hazır bloklardan oluşturmanıza olanak tanıyan oluşturucular (No-code platformları) mevcuttur. Ancak, karmaşık mantık ve benzersiz tasarım için bir geliştiriciden yardım almanız veya web programlamanın temellerini öğrenmeniz gerekecektir.

Bağlı mini uygulamayı nasıl silerim? Kullanıcının hiçbir şey silmesine gerek yoktur. Bot ile sohbet geçmişini temizlemek veya spam yapıyorsa botu engellemek yeterlidir. Uygulama önbelleği, mesajlaşma uygulamasının önbelleği bir sonraki güncellendiğinde otomatik olarak temizlenecektir.