Telegram Mini App (TMA) Geliştirme Hataları ve Bunlardan Nasıl Kaçınılır

Özet

• Çoğu Telegram Mini App geliştirme hatası, Mini App'i normal bir web sitesi olarak ele almak yerine beş farklı Telegram istemcisi içinde çalışan bir WebView olarak ele almakla kaynaklanır.
• En önemli düzeltme, sunucunuzda initData kontrolü yapmak ve eski payload'ları auth_date ile reddetmektir; initDataUnsafe asla yetkilendirme için güvenilmemelidir.
• Düzen hataları genellikle 100vh ve kaybolan güvenli alan yerleşimleri ile bağlantılıdır, CSS framework'leri ile değil.
• Bot API 10.2 (14 Temmuz 2026), Mini App'in kendi alanı dışındaki bir kaynaktan çağrılan Mini App yöntemlerini engeller, bu nedenle iframe tabanlı ve çok alanlı kurulumlar, akış yeniden tasarlanmadıkça bozulur.
• Para kazanma hataları, kod hataları kadar maliyetlidir: değer oluşturmadan önce yerleştirilen reklamlar, debug: true üretime gönderilir ve yalnızca istemciye özgü ödül mantığı, geliri azaltır veya dolandırıcılığı davet eder.

Bu makale, üretimde en sık ortaya çıkan hataları — yetkilendirme, görünüm, depolama, versiyonlama, lansman parametreleri ve para kazanma — ele alır ve her biri için kesin çözümü, ilgili yöntem adları ve Bot API sürümleriyle birlikte sunar. Sonunda bir teşhis tablosu ve her dağıtım öncesi çalıştırabileceğiniz bir ön sürüm kontrol listesi bulunmaktadır.

Neden Telegram Mini App geliştirme hataları ortaya çıkar

Bir Mini Uygulama, kontrol etmediğiniz bir uygulamanın içinde çalışır. Bu üç sınırlama yaratır ve aşağıdaki her hatanın hemen hemen hepsi bunlardan birinden kaynaklanır.

• İstemci bir tarayıcı değildir. Telegram'ın iOS'taki WebView'i, Android'inkinden farklı davranır ve her ikisi de Telegram Desktop'tan farklıdır. Depolama, klavye kullanım şekli ve jestler en çok farklılık gösterdiği alanlardır.
• Her istemci farklı bir API sürümünü destekler. Eski bir Telegram sürümündeki bir kullanıcı, çağırdığınız yöntemi bulamayabilir ve herhangi bir polyfill yoktur.
• Telegram etrafınızdaki arayüze sahiptir. Başlık, alt çubuk, kapatma jesti ve güvenli alan Telegram'a aittir, bu yüzden tasarımınız bunlara göre çalışmak zorundadır.

Okumak resmi Telegram Mini Uygulama belgeleri bir kez yeterli değil — Bot API değişiklik günlüğü kırıcı değişikliklerin yer aldığı yerdir ve yalnızca 2026'da birkaç kez taşınmıştır.

Güvenlik ve başlatma verisi hataları

En yaygın güvenlik hatası, müşteriden gelen verileri kimlik kanıtı olarak değerlendirmektir. Telegram, size imzalı bir yük gönderir; doğrulama sizin işiniz.

1. İmzanın kontrol edilmeden initDataUnsafe'a güvenmek

initData, Telegram'ın bir Mini App'e geçirdiği ham, imzalı başlatma verisidir; initDataUnsafe ise kullanım kolaylığı için zaten ayrıştırılmış aynı veridir. İsmin içindeki Unsafe kelimesi bir uyarıdır, etiket değildir. Telegram'ın belgeleri, verinin botun sunucusunda kullanılmadan önce doğrulanması gerektiğini açıkça belirtmektedir.

Bundan nasıl kaçınılır: ham initData dizesini arka uca gönderin ve orada doğrulayın. Tüm anahtar-değer çiftlerinden (hash hariç) alfabetik sırayla ve satır sonlarıyla birleştirerek veri kontrol dizesini oluşturun; HMAC-SHA256(bot_token, "WebAppData") ile bir gizli anahtar türetin; HMAC-SHA256(data_check_string, secret_key) hesaplayın; hash ile sürekli zaman diliminde karşılaştırın. Bot token'ını asla müşteriye göndermeyin ve düz bir istek parametresi olarak gelen bir kullanıcı ID'sini kabul etmeyin.

Üçüncü bir taraf, bot token'ınızı elinde tutmadan bir başlatmayı doğrulaması gerektiğinde, Telegram Mini Apps init verisi referansı. Orada sıkça karşılaşılan uygulama tuzağı: imza, dolgu olmadan base64url biçiminde kodlanır, bu nedenle birkaç dilin = karakterlerini geri yüklemesi gerekir.

2. auth_date'ın ne kadar eski olduğunu kontrol etmemek

Geçerli bir imza, yükün Telegram'dan geldiğini kanıtlar, ancak bunun birkaç dakika önce geldiğini değil. Bir süre sona erme kontrolü olmadan, yakalanan initData dizesi sonsuza kadar geçerlidir.

Bundan nasıl kaçınılır: auth_date'ı sabit bir aralıktan daha eski olan herhangi bir yükü reddedin — 24 saat yaygın bir varsayılandır ve parayı veya uygulama içi para birimini hareket ettiren uygulamalar için daha kısa pencereler uygundur. Doğrulanan yükü kendi oturum token'ınız için bir kez değiştirin ve sonraki her isteği o token ile kimlik doğrulayıp onaylayın. is older than a fixed window — 24 hours is a common default, and shorter windows are appropriate for apps that move money or in-app currency. Exchange the validated payload once for your own session token, and authenticate every later request with that token.

3. Oturum jetonlarını localStorage'da tutmak

localStorage Telegram'ın WebView'ında güvenilir değildir. Mini Apps üretimi hakkında yazanlar, iOS'ta ve bazı Linux masaüstü sürümlerinde hiç kalmayabileceğini rapor ediyor, bu nedenle bir yeniden başlatma bunu temizleyebilir ve oturumu da beraberinde alabilir.

Bundan nasıl kaçınılır: alışkanlık yerine amaca göre depolama seçin.

Bir kullanıcının sahip olduğu veya kazandığı her şey sizin sunucunuzda bulunmalıdır.

4. Farklı bir alandan Mini App yöntemlerini çağırma

Bu yeni ve çalışan uygulamaları bozdu. 14 Temmuz 2026'da yayınlanan Bot API 10.2, Mini App yöntemlerinin orijinal Mini App alanından farklı kaynaklardan kullanılmasını yasaklayarak Mini App güvenliğini artırdı.

Bunu nasıl önlersiniz: Mini App için kayıtlı alan adında Telegram.WebApp yöntemlerini çağıran her ekranı koruyun. Akışınızın bir kısmı bir ödeme sağlayıcısında, bir ortağınızın sayfasında veya gömülü bir iFrame içinde yaşıyorsa, Telegram API çağrılarını kendi kökeninize geri taşıyın ve sonuçları arka ucunuz aracılığıyla bağlamlar arasında aktarın. Hala çalıştığını varsaymadan önce güncel bir istemci üzerinde tam akışı test edin.

Düzen ve görünüm hataları

Görünüm hataları en görünür kategori olup — kesilmiş bir CTA hemen fark edilir — ve en önlenebilir olanlardır.

1. Telegram görünüm yüksekliği yerine 100vh kullanmak

Mobilde, Mini App, kullanıcının sürükleyebileceği bir alt sayfa olarak açılır. 100vh, görünen alanla eşleşmeyen bir tarayıcı görünümünü ifade eder, bu nedenle içerik katman altında veya Telegram'ın kendi arayüzünün altında kalır.

Bunu nasıl önlersiniz: başlarken expand() çağırın, ardından düzeninizi viewportHeight ve viewportStableHeight üzerinden boyutlandırın. Sıçrama yapmaması gereken her şey için viewportStableHeight kullanın — bu değer sürükleme ve klavye animasyonları sırasında geçiş durumlarını dikkate almazken, viewportHeight sürekli olarak güncellenir. Görünüm değişikliği olayına abone olun ve yalnızca stabil değerlerde yeniden render yapın.

2. Güvenli alan iç kenar boşluklarını görmezden gelmek

Bot API 8.0, birbirine karıştırılması yaygın olan iki ayrı iç kenar nesnesi tanıttı. safeAreaInset, çentik ve ana ekran göstergesi gibi sistem alanlarını tanımlar. contentSafeAreaInset, Telegram'ın kendi arayüz elemanları tarafından kaplanan alanı tanımlar.

Bunu nasıl önlersiniz: her ikisini de uygulayın. Sistem iç kenar boşlukları donanım kesintilerine karşı koruma sağlar; içerik iç kenar boşlukları başlığınızı Telegram'ın başlığından uzak tutar. Tam ekran modunda — aynı zamanda eklenen Mini Apps 2.0 sürümü — insets daha önemli, daha az değil, çünkü Telegram artık o alanı sizin için ayırmıyor.

3. Oyunlarda dikey kaydırmaları açık bırakma

Uygulamanızda aşağı doğru bir kaydırma, içeriğinizi kaydırmak yerine Mini App'i kapatabilir. Oyunlar ve sürüklemeye dayalı arayüzlerde, kullanıcılar uygulamanın donduğunu düşünebilir.

Bundan nasıl kaçınılır: disableVerticalSwipes() (Bot API 7.7+) özel jestlere sahip ekranlarda çağırın ve standart kaydırmanın beklendiği yerlerde yeniden etkinleştirin. Bununla birlikte enableClosingConfirmation() (Bot API 6.2+) kaydedilmemiş giriş içeren herhangi bir ekranda kullanın.

4. Özel bir geri butonu oluşturma

Kendi geri okunuz, Telegram navigasyonu ve Android donanım geri butonuyla rekabet eder. Kullanıcılar, farklı davranan iki geri kontrol alır.

Bundan nasıl kaçınılır: BackButton (Bot API 6.1+), bunu yönlendiricinize bağlayın ve rotalar değiştikçe gösterin veya gizleyin. İki navigasyon yığını değil, bir tane tutun.

Gerçek cihazlarda performans hataları

Çoğu Mini App trafiği orta düzey ve bütçe dostu Android telefonlardan gelir. Oturum, bir sohbette bir dokunuşla başlar, bu nedenle kullanıcılar bunun bir mesaj kadar hızlı açılmasını bekler.

• Ağır bir ilk paket. Rotaları ayırın, ilk ekran için gerekli olmayan her şeyi erteleyin ve başlangıç verisini birincil performans metriği olarak değerlendirin.
• SSR'a bağlı olarak. Telegram API'leri window gerektirir, bu nedenle sunucu tarafı render'ı onlara erişemez. Next.js projeleri, bir sunucu bileşeni içinde ilk Telegram çağrısında bu sorunu yaşar; Telegram'a bağımlı mantığı istemci bileşenlerinde tutun ve SDK hazır olana kadar bir iskelet render edin.
• Animasyon bütçesi cihazları render edemez. Karmaşık animasyonlar, WebView içinde düşük donanımda keskin bir şekilde bozulur. Sadece transform ve opacity'yi animasyonlayın ve kare düşüşü gerçekleştiğinde efektleri azaltın.
• Yükleme durumu yok. Telegram, geliştiricilerin Mini App yükleme ekranını özelleştirmesine izin verir; beyaz alan yerine iskelet gösteren ilk boyama, erken çıkışları ölçülebilir şekilde azaltır.

Versiyon ve platform hataları

Bir kullanıcının Telegram sürümünün desteklemediği bir metodu çağırmak, sessizce başarısız olur veya hata fırlatır ve her iki sonuç da bozuk bir uygulama izlenimi yaratır. Çözüm, bir versiyon tabanı artı açık bir kapama gerektirir.

Bunu nasıl önlersiniz: uygulamanızın desteklediği minimum Bot API sürümünü belirleyin, o tabanın üzerindeki her şeyi isVersionAtLeast() (Bot API 6.1+) ile kapatın ve her kapalı özellik için çalışan bir geri dönüş gönderin.

Telegram Web'de yalnızca test yapmak bu sorunların çoğunu gizliyor. iOS, Android ve en az bir masaüstü istemcisinde sürüm adayını çalıştırın. Cihaz üzerinde hata ayıklama için, Chrome DevTools Android'i kapsar ve Safari Web Inspector iOS'u; her ikisi de mevcut değilse, Eruda gibi bir uygulama içi konsol, kablo olmadan çalışma hatalarını görünür hale getirir.

Startapp ve derin bağlantı hataları

Mini Apps tek bir başlatma parametresi alır, startapp, ve ekipler genellikle daha fazlasını varsayan bir derin bağlantı şeması tasarlar.

Bundan nasıl kaçınılır: bir ayrıştırıcı ile kontrol ettiğiniz bir startapp dizesine birden fazla değeri kodlayın — ref__campaign__level yaygın bir kalıptır — ve doğrulamadan sonra istemcide ayrıştırın. Bir yönlendirme atfetmeden veya bir bonus verirken sunucudan doğrulanmış initData parametresini okuyun, çünkü bir başlatma parametresi tek başına sahtelemek kolaydır. Bu adımı atlayan derin bağlantı yönetimi, Telegram Mini Apps'de yönlendirme sahtekarlığının sık bir kaynağıdır.

Reklam entegrasyonu hataları

Reklam entegrasyonu genellikle sağlam kod ile zayıf ürün kararlarının kesiştiği yerdir. Bu hatalar uygulamayı çökertmez — eCPM'yi düşürür, ödülleri bozar veya moderasyonu başarısız kılar. Eğer bir yaklaşım seçiyorsanız, Telegram Mini Apps ve para kazanma fırsatlarına giriş her entegrasyon kodunu yazmadan önce mevcut olan formatları kapsar.

1. Reklamı çok erken göstermek

İlk ekranda bir ara yüz reklamı, yeni kullanıcı kazandığınız kişinin dikkatini kaybetmenin en hızlı yoludur. Henüz ürünü görmedikleri için kesilecek bir şey yoktur.

Bunu nasıl önlersiniz: Kullanıcının bir şeyi tamamladığı anları — bir seviye, bir görev, bir talep — haritalayın ve reklamları bu sınırların yanına yerleştirin. Ödüllü formatlar, ödül kullanıcının zaten istediği bir şey olduğunda en iyi şekilde çalışır: bir ekstra yaşam, bir hızlanma, ek bir bakiye.

2. Hata ayıklama modunu üretimde açık bırakmak

AdsGram SDK, test reklamları sunan ve günlüğe kaydedici loglar yazdıran bir debug bayrağını kabul eder. AdsGram belgeleri, bunun kaldırılması veya false olarak ayarlanması gerektiğini açıkça belirtmektedir. Test izlenimleri istatistik üretmez ve ödül geri çağırmalarını tetiklemez; bu nedenle gönderilen debug: true, görünüşte düzgün bir uygulama oluşturur ve hiçbir şey kazandırmaz.

3. Her reklam gösteriminde init() çağırmak

window.Adsgram.init({ blockId }) bir AdController döner. AdsGram belgeleri, başlatmanın her blockId⟧ için bir kez gerçekleştiğini ve tekrar edilen çağrıların aynı kontrolcü örneğini döndürdüğünü belirtir. and repeated calls return the same controller instance.

Bunu nasıl önlersiniz: Kontrolörü uygulama başlangıcında bir kez oluşturun, referansı saklayın ve her yerleştirme için show() çağrısını yapın. Tipik bir ödüllü entegrasyon şöyle görünür:

<script src="https://sad.adsgram.ai/js/sad.min.js"></script>

const AdController = window.Adsgram.init({ blockId: "your-block-id" });

AdController.show()
.then(() => {
// reklam sonuna kadar izlendi — ödülü vermek için backend'inize başvurun
})
.catch((result) => {
// reklam başarısız oldu veya erken kapatıldı — hiçbir şey vermeyin
console.warn(result);
});

4. show() hatalarını ele almamak

show(), reklam oynatılamadığında veya kullanıcı erken çıktığında reddedilir. catch() içermeyen bir entegrasyon, vermemesi gereken ödülleri verir veya kullanıcıyı yüklenme durumunda bırakır.

Bunu nasıl önlersiniz: reddetme yolunu açıkça yönetin ve SDK olaylarına abone olun — onStart, onSkip, onReward, onComplete, onError, onBannerNotFound, onNonStopShow, onTooLongSession. onBannerNotFound, lansman sırasında dikkat edilmesi gereken olaydır: genellikle o coğrafya veya blok için dolgu ihtiyacının düşük olduğunu gösterir, kodun yanlış olduğunu değil. Her zaman bir ödül veya bir sonraki ekran için reklam içermeyen bir yol bıraktığınızdan emin olun, böylece kaybolan bir reklam asla çıkmaz bir sokak haline gelmez.

5. Ödülü yalnızca istemcide vermek

Eğer ödül istemci kodu ile yazıldıysa, yeniden oynatılabilir. Bu, initDataUnsafe'a güvenmekle aynı hata sınıfındadır.

Bunu nasıl önlersiniz: ödülleri backend'iniz aracılığıyla verin. AdsGram, daha büyük yayınevleri için de bir sunucu-arası geri bildirim sunmaktadır: günde ortalama 50.000'den fazla kullanıcıya sahip uygulamalar, bir ödül URL'si yapılandırabilir ve AdsGram, istemci tarafındaki ödülden sonra kullanıcının telegramId'sini içeren bir GET isteği gönderir. Uç noktası, 443 numaralı portta HTTPS GET kabul etmeli ve [userId] yer tutucusunu içermelidir; örneğin, https://example.com/reward?userid=[userId]. Geri bildirim, hata ayıklama modunda gerçekleşmez.

6. Reklamları kullanıcıların göremeyeceği yerlere yerleştirmek

Yerleştirme kuralları görünürlükle ilgilidir, tasarımla değil. AdsGram platformunda bir izlenim, blok %50'den fazla görünürken sürekli olarak iki saniye izlendikten sonra sayılır.

Bunu nasıl önlersiniz: asla çökertilmiş, ekrandan dışarıda veya sıfır yüksekliğinde bir konteyner içinde bir reklam bloğu render etmeyin, aynı ekran alanında blokları üst üste yerleştirmeyin ve Mini App minimumda olduğu sürede bir gösterimi tetiklemeyin. AdsGram, her uygulamada 10'a kadar reklam bloğuna izin verir; bu, yerleştirmeleri bağlama göre ayırmak için yeterlidir — bir seviye tamamlama için, bir günlük bonus için, bir görev duvarı için — her yerde aynı bloğu ateşlemek yerine.

Lansman ve moderasyon hataları

Çoğu reddetme, uygulama tamamlanmadığı için olur, kuralı ihlal ettiği için değil. AdsGram platformunda, bir Mini App moderasyon sırasında mevcut olmalı ve doğru çalışmalıdır; bu, genellikle hafta içi 4-6 saat içinde ve hafta sonları 6-10 saat içinde tamamlanır.

Yaygın lansman aşaması hataları:

• Kullanıcı girişi gerektiren veya beyaz listeye alınmış bir yapıyı gönderirken, moderatörler bir hata ekranı görür.
• Sadece bir platformda bozulan akışlar, genellikle iOS klavye kullanımı veya masaüstü düzeni ile ilgilidir.
• Kuralları okumadan belirlenen ödeme beklentileri: AdsGram varsayılan olarak TON ağı üzerinde USDT ile ödeme yapar. USDT TRC20 ve fiat transferleri mevcuttur, minimum $100 çekim limiti vardır ve işleme gün içinde 24 saat, hafta sonlarında ise 48 saate kadar sürer.
• Reklam hunisinde analiz yok, bu da düşük doluluğu bozuk bir yerleştirmeden ayırt etmeyi imkansız kılar. Eşleştirmeden önce ağları karşılaştırıyorsanız, bizimAdsGram ile Monetag karşılaştırmasıneye göre ölçüm yapmanız gerektiğini belirtir.

Belirti ve neden tablo

Bu sorunları lansmandan önce çözmek, destek biletleriyle takip etmekten daha az maliyetlidir ve sadece çalışan bir Mini App ile kullanıcıları çeken ve kazanç sağlayan bir Mini App'i ayıran şeydir. Teknik alt yapı stabil olduğunda, Telegram Mini Apps para kazanma bir yapılandırma görevi haline gelir, kurtarma operasyonu değil — ve formatlar ile talep hakkında daha derin bilgiye Telegram Mini Apps para kazanma ve reklam potansiyeli başlığımızda ulaşabilirsiniz.

SSS

1. Neden Telegram Mini App'im açılmıyor?
   Genellikle nedenler, başarısız bir başlangıç, ilk render öncesinde ele alınmamış bir hata veya istemci depolamasıyla kaybolan bir oturumdur. Uygulama URL'sinin HTTPS üzerinden erişilebilir olduğundan, SDK'nın herhangi bir Telegram API çağrısından önce hazır olduğundan ve hiçbir kodun localStorage'nın bir yeniden başlangıçta hayatta kalmasına bağımlı olmadığından emin olun. Eğer uygulama Android'de açılıyor ama iOS'ta açılmıyorsa, aynı derlemeyi Safari Web Inspector ile test edin.
2. Bir tarayıcıda Telegram Mini App'i nasıl açar ve test ederim?
   Telegram dışında herhangi bir başlatma parametresi yoktur, bu nedenle SDK bunları alabileceğini raporlamaz. Yerel çalışma için, bir ortam kontrolü yapın ve Telegram ortamını sahteleyerek uygulamanın normal bir tarayıcıda görüntülenmesini sağlayın. Geliştirme sunucunuzu bir tünel aracılığıyla, örneğin bir VS Code geliştirme tüneli veya ngrok ile dışa açın, o HTTPS URL'sini BotFather'da ayarlayın ve uygulamayı bot üzerinden açın.
3. Telegram Mini App'inde init verilerini nasıl doğrularım?
   Ham initData dizesini arka uçunuza gönderin. Tüm anahtar-değer çiftlerinden hash hariç, alfabetik olarak sıralayın ve yeni satırlar ile birleştirerek veri kontrol dizesini oluşturun, HMAC-SHA256(bot_token, "WebAppData") ile bir gizli anahtar türetin, HMAC-SHA256(data_check_string, secret) hesaplayın ve bunu hash ile karşılaştırın. auth_date'in tazelik pencerenizin dışında olduğu yüklemeleri reddedin, ardından kendi oturum tokeninizi verin.
4. Telegram Mini App'i iOS ve Android'de nasıl hata ayıklayabilirim?
   Android için USB uzaktan hata ayıklama ile Chrome DevTools'u ve iOS için Safari Web Inspector'ı kullanın. Her ikisi de mevcut değilse — bir test cihazı, başkasının cihazında bir yapı — bir kablo olmadan çalışma zamanı hatalarının görünür olabilmesi için Eruda gibi bir uygulama içi konsol ekleyin. Her hatayı gerçek bir Telegram istemcisinde yeniden oluşturun, çünkü Telegram Web çoğu WebView'e özgü davranışı gizler.
5. Telegram Mini App'te localStorage kullanabilir miyim?
   Telegram'ın WebView'inde, localStorage iOS ve bazı masaüstü sürümlerinde kalıcı olmayabilir, bu nedenle bir yeniden başlatma onu temizleyebilir. Hesabı takip etmesi gereken kullanıcı ayarları için CloudStorage, yerel kalıcılık için DeviceStorage veya SecureStorage kullanın (Bot API 9.0'dan), ve oturumlar, bakiyeler ve tüm haklar için kendi arka ucunuzu kullanın.
6. Bot API 10.2 mevcut Mini App'leri bozuyor mu?
   Bozabilir. 14 Temmuz 2026'da yayımlanan Bot API 10.2, Mini App yöntemlerinin Mini App'in orijinal alanı dışındaki kaynaklardan kullanımını yasaklar. Telegram.WebApp yöntemlerini gömülü bir iframe, bir ortak sayfa veya ikincil bir alan üzerinden çağıran uygulamalar, güncellenmiş istemcilerde bu çağrıların başarısız olduğunu görecektir. Tüm Telegram API çağrılarını kayıtlı alanda tutun ve üçüncü taraflarla veri alışverişini arka uç üzerinden gerçekleştirin.