Mini uygulama geliştirme kuralları

10 altın kural

1. <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"> kullan; sabit piksel genişlik verme.
2. html öğesine asla overflow:hidden + height:100% verme. Kaydırmayı engellemen gerekiyorsa yalnız body'ye uygula.
3. Ekranın altına sabitlenmiş (position:fixed) pencere/form açma; formları sayfa akışında göster.
4. İki sütunlu ızgaralarda minmax(0,1fr) kullan, form alanlarına min-width:0;width:100% ver.
5. Yüksekliği window.innerHeight ile hesapla ve resize olayında yeniden hesapla.
6. CSS/JS dosyalarına sürüm eki koy (app.js?v=…); yoksa kullanıcılar saatlerce eski dosyayı görür.
7. backdrop-filter, ağır filter ve çok katmanlı gölgelerden kaçın.
8. Renkleri narX tema değişkenlerinden al (--ix-bg, --ix-text …); koyu tema kendiliğinden çalışır.
9. Yükleme bitince iletx.ready() çağır; çağırmazsan kullanıcı açılış ekranında bekler.
10. Kullanıcı verisini localStorage'a değil iletx.storage'a yaz; cihaz değişince kaybolmaz.

Ekran ve düzen

Ekran ölçüleri

• Hedef genişlik 320–480 px (telefon). Tablet ve web'de içeriği en çok 560–640 px genişlikte ortala (max-width:560px;margin:0 auto).
• Kullanılabilir yükseklik, narX'in üst çubuğu ve sistem çubukları düşüldükten sonra kalan alandır; telefonda genelde 560–760 px. Sabit yükseklik varsayma, innerHeight kullan.
• Sayfa yatay kaydırma üretmemeli: scrollWidth ≤ innerWidth. Güvence için html,body{overflow-x:hidden;max-width:100%}.
• Alt kenarda çentik ve hareket çubuğu için padding-bottom:env(safe-area-inset-bottom) ekle.
• narX'in ana düğmesini (iletx.ui.mainButton) kullanıyorsan içeriğin altında en az 96 px boşluk bırak.

Önerilen temel CSS

*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
html,body{overflow-x:hidden;max-width:100%}
body{margin:0;background:var(--ix-bg);color:var(--ix-text);font:15px/1.45 system-ui,sans-serif;
     padding-bottom:calc(96px + env(safe-area-inset-bottom))}
main{max-width:560px;margin:0 auto;padding:12px 14px}
.f2{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:10px}
input,select,textarea{width:100%;min-width:0;font:inherit;-webkit-appearance:none;appearance:none}

Tam ekran (oyun, harita, çizim) düzeni

• Kaydırmayı body{overflow:hidden;touch-action:none} ile kapat; html'e dokunma.
• Oyun alanını genişliğe ve yüksekliğe sığacak şekilde hesapla: boyut = min(genişlik, (innerHeight − üst şerit − alt düğmeler) × oran).
• Ekranın altına yalnız küçük bir düğme şeridi sabitleyebilirsin; büyük form ya da pencere sabitleme.
• Canvas'ı devicePixelRatio ile ölçekle (bulanık görünmesin).

Formlar ve klavye

• Formu açarken ana içeriği gizleyip formu sayfanın başından göster (ayrı sayfa gibi). Alttan açılan sabit pencere eski WebView'larda klavyenin altında kalır ya da yanlış boyutlanır.
• narX, klavye açılınca mini uygulama alanını küçültür ve odaklanan alanı görünür tutar; ek scrollIntoView gerekmez.
• Sayı girişinde inputmode="decimal"/"numeric", tarih için type="date" kullan; tarih alanını da diğerleri gibi biçimlendir (yükseklik, kenarlık, appearance:none).
• Uzun formlarda max-height ile kısıtlama yapma; sayfa doğal olarak kaysın.

Önbellek ve sürüm

• CDN, CSS/JS/görsel dosyalarını 4 saate kadar önbellekte tutabilir. HTML her açılışta tazelenir.
• Her yayında dosya adresini değiştir: <script src="app.js?v=2026101801">. narX'te barındırılan uygulamalarda sunucu bu eki kendiliğinden ekler.
• SDK'yı her zaman https://web.narx.tr/sdk/iletx.js adresinden yükle; kendi kopyanı tutma.

Güvenlik ve ağ

• Uygulaman kendi kökeninde çalışır; narX oturumuna, çerezlerine ve diğer uygulamalara erişemez. Tüm narX işlemleri SDK köprüsünden geçer.
• Adresin HTTPS olmalı (geliştirmede yalnız http://localhost).
• Android'de uygulama yalnız kendi alan adında gezinebilir; başka adresler sistem tarayıcısında açılır. Dış bağlantılar için iletx.openLink(url) kullan.
• Kullanıcı kimliğine istemciden güvenme: sunucunda initData imzasını doğrula.
• eval, uzaktan betik enjeksiyonu ve gizli izleme kodları incelemede reddedilir.

İzinler ve veri

• Yalnız gerçekten kullandığın izinleri bildir (chat.members, share.chat, contacts.pick, media.pick, location, profile.email). Başvuruda her izin için gerekçe zorunludur.
• İzni ilk ihtiyaç anında iste; reddedilirse çökme, anlaşılır bir mesaj göster (e.code === 'permission_denied').
• Kullanıcının vazgeçmesi hata değildir: e.code === 'cancelled' durumunda sessizce devam et.
• Grupla ortak veride (iletx.storage + {chat}) her kullanıcı/öğe için ayrı anahtar kullan (ör. rv:<etkinlik>:<kullanıcı>). Tek büyük nesneyi herkes yazarsa değişiklikler birbirini ezer.
• Kişisel veriyi üçüncü taraflara gönderme; gizlilik politikanda neyi neden topladığını yaz.

Tasarım

• Dokunma hedefleri en az 44×44 px; oyun kontrolleri için 56–68 px.
• Metin en az 13 px; ana metin 15–16 px.
• Tema değişkenleri: --ix-bg --ix-card --ix-text --ix-muted --ix-line --ix-brand --ix-lime --ix-navy --ix-danger. Sabit beyaz/siyah kullanma.
• Başlığı iletx.ui.setTitle() ile ver; kendi üst çubuğunu çizme (narX'in çubuğu zaten var).
• Birincil eylem için alttaki vurgu renkli ana düğmeyi kullan: iletx.ui.mainButton.show('Gönder', fn).
• Emojiler cihaz yazı tipine göre farklı görünür; kritik bilgi için SVG simge kullan.

Oyunlar için ek kurallar

• Sayfa arka plana geçince (visibilitychange) oyunu duraklat.
• Düğmelerde pointerdown kullan (gecikme olmaz); basılı tutunca tekrar eden hareket için zamanlayıcı kullan.
• Rekoru kişisel depoya, grup sıralamasını sohbet deposuna hs:<kullanıcı> anahtarıyla yaz.
• Skor paylaşımında görsel ekle (card.image, 1200×630, HTTPS); görselli kartlar çok daha fazla tıklanır.

Sınırlar

Sık hatalar ve çözümleri

Aşağıdakilerin hepsi narX'in kendi mini uygulamalarında karşılaşıp çözdüğümüz gerçek sorunlardır.

Yayın öncesi kontrol listesi

• ☐ 360×640, 392×800 ve 412×915 ekranlarda yatay kaydırma yok, her şey görünür.
• ☐ Android narX içinde açılıyor (beyaz ekran yok), web'de de açılıyor.
• ☐ Açık ve koyu temada okunur.
• ☐ Klavye açılınca form alanları görünür; uzun form kayar.
• ☐ İzin reddi ve "vazgeç" durumlarında çökme yok.
• ☐ iletx.ready() her yolda çağrılıyor.
• ☐ Dosya adreslerinde sürüm eki var.
• ☐ Sohbet dışından açılınca (bağlamsız) anlamlı bir ekran gösteriliyor.
• ☐ Paylaşım kartı sohbette doğru görünüyor, karta dokununca doğru içerik açılıyor.
• ☐ Gizlilik politikası adresi çalışıyor.

Mağaza inceleme ölçütleri

• Çalışırlık: kontrol listesindeki maddeler; ilk açılışta 3 saniye içinde içerik.
• İzinler: her izin gerçekten kullanılıyor ve gerekçesi açık.
• İçerik: yasa dışı, yanıltıcı, kumar ya da yetişkin içerik yok; tescilli marka/isim izinsiz kullanılmıyor.
• Gizlilik: gizlilik politikası var; kişisel veri üçüncü taraflara izinsiz aktarılmıyor.
• Spam: kullanıcı onayı olmadan sohbete mesaj/kart gönderilmiyor; bot bildirimleri makul sıklıkta.
• Reddedilen başvurular gerekçesiyle @botfather üzerinden bildirilir; düzeltip yeniden başvurabilirsin.