Android, bir web sitesini ana ekrana eklerken ikon kaynağı olarak manifest.json dosyasını okur. Bu dosyadaki icons dizisi eksik veya yanlış tanımlanmışsa Chrome sessizce bir yer tutucu gösterir. Favicon.ico devreye girmez; PWA ikon sistemi, klasik favicon altyapısından bağımsız çalışır.
Bu bağımsızlığı göz ardı eden kurulumlar genellikle aynı noktada takılır: tarayıcıda doğru görünen ikon, Android ana ekranında ya hiç görünmez ya da kırpılmış halde çıkar. Sorun manifest'tedir, favicon'da değil.
manifest.json'da icon dizisi nasıl yazılır
icons dizisindeki her nesne dört alanı taşımalıdır: src, sizes, type ve purpose. Chrome bu dört alanın tamamını ararken eksik olan girişleri eşleştirme dışında bırakır. Yaygın bir hata, type alanını atlamaktır; bu alan olmadan Chrome ikonun MIME türünü tahmin edemez ve girişi geçersiz sayabilir.
{
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-192-maskable.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-512-maskable.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}purpose alanında any maskable birlikte boşlukla ayrılmış biçimde yazılabilir; Chrome bunu iki ayrı değer olarak işler. Ancak bu kısa yolun bir tuzağı vardır: maskable amacı olan ikon, safe zone kurallarını karşılamak zorundadır. Aynı dosyayı hem any hem maskable olarak işaretlemek, safe zone uygulanmamış bir görseli maskable olarak sunmak anlamına gelir; Android'de kırpma bu durumda ortaya çıkar.
Ayrı dosya kullanmak bu belirsizliği kaldırır.
Tüm ikon dosyalarında PNG tercih edin. WebP desteği Android sürümüne ve üreticinin özelleştirmesine göre değişir; bazı eski cihazlarda manifest'teki WebP girişleri sessizce atlanır. PNG bu uyumluluk sorununu yaşatmaz. Farklı formatlardaki görsel dosyalarınızı uygun formata dönüştürmek için resim dönüştürme aracını kullanabilirsiniz.
Maskable icon ve safe zone
Android 8.0 ile gelen adaptif ikon sistemi, uygulama ikonunu bir maske şablonuna göre kırpar. Bu şablon cihaz üreticisi tarafından belirlenir; bir Sony cihazında daire olan şekil, başka bir üreticinin arayüzünde farklı görünebilir. PWA'nın bu sisteme uyum sağlaması için tasarlanan "maskable icon" formatı, ikonun bu kırpmaya hazır olduğunu bildirir.
Kırpma kasıtlı, hata değil.
Safe zone kuralı şudur: ikonun içindeki logo veya simge, toplam görselin yüzde seksenini geçmemeli. Her kenardan yaklaşık yüzde onda birlik boşluk bırakıldığında, kırpma gerçekleşse bile logonun tamamı görünür kalır. 192x192 piksellik bir ikonun safe zone'u yaklaşık 154x154 pikseldir; bu sınırları aşan logolar kırpıldığında kesilmiş ya da asimetrik görünür.
Bu hesabı manuel yapmak yerine Maskable.app gibi araçlarla görsel olarak test edebilirsiniz. Araç, ikonunuzun farklı maske şekilleri altında nasıl göründüğünü anlık olarak gösterir. Tasarımı üretime almadan önce bu testi yapmak, kurulum sonrası sürpriz kırpma sorunlarını büyük ölçüde önler. Ürettiğiniz ikonları manifest'e eklemeden önce safe zone uyumunu doğrulamak yerinde bir pratiktir.
Masaüstü tarayıcılar bu kırpmayı uygulamaz. Sorun yalnızca Android ana ekranında ve bazı PWA başlangıç ekranlarında görünür; bu yüzden geliştirme ortamında sorunsuz görünen ikon, cihazda kurulunca bozuk çıkabilir. Yalnızca masaüstü tarayıcıda test etmek bu hatayı gözden kaçırmanın en yaygın nedenidir.
Zorunlu boyutlar ve boyut seçim mantığı
Chrome'un PWA kurulum ölçütlerine göre 192x192 ve 512x512 piksel zorunludur. 192x192, ana ekrana ekleme diyaloğu ve görev yöneticisi ikonları için kullanılır; 512x512 ise başlangıç ekranı için gereklidir. Bu iki boyuttan biri eksikse Chrome kurulum bildirimi göstermeyebilir.
Ara boyutlar (128x128, 256x256, 384x384) zorunlu değildir ama geniş cihaz desteği hedefliyorsanız eklenebilir. Samsung Internet ve bazı eski Android sürümleri farklı boyut eşiklerini tercih edebilir. Minimal kurulum için 192 ve 512 yeterlidir; ekstra boyutlar yalnızca uyumluluk kapsamını genişletmek amacıyla kullanılmalıdır. Her ek boyut, aynı anda maskable ve any varyantını gerektireceğinden dosya sayısı hızla artar; bunu göz önünde bulundurarak boyut matrisini bilinçli tutun.
- 192x192: Chrome ana ekran ikonu ve görev yöneticisi; zorunlu
- 512x512: Başlangıç ekranı; zorunlu
- Maskable varyantlar: Her iki boyut için ayrı, safe zone uyumlu dosyalar
- Ara boyutlar: Opsiyonel; Samsung Internet ve eski Android desteği için
Başlangıç ekranı rengi yalnızca ikon dosyasından değil, manifest.json'daki background_color alanından da alınır. Chrome, uygulama başlatılırken bu rengi arka plan olarak kullanır; 512x512'lik ikon ortaya yerleştirilir. background_color tanımlanmamışsa başlangıç ekranı beyaz ya da cihaz varsayılanında görünür. Marka rengini tutturmak istiyorsanız bu alanı manifest'e eklemeniz gerekir; kurulduktan sonra bu değeri değiştirmek uygulamanın yeniden yüklenmesini zorunlu kılar.
İkon dosyalarını kaynaktan hazırlamak
PWA ikonu için tasarım sürecini en baştan kurarken kare boyut zorunludur. 400x600 gibi dikdörtgen bir logo dosyası, kare ikona dönüştürülürken en, sıkıştırılır ya da boşlukla doldurulur; her iki yöntem de küçük boyutlarda çirkin sonuç üretir. Başlangıç tasarımını kare tuval üzerinde oluşturmak, sonradan boyut uyarlama sürtünmesini ortadan kaldırır.
Kaynak dosya olarak SVG kullanmak büyük avantaj sağlar. Tek bir SVG'den Inkscape, Figma veya Illustrator aracılığıyla 192x192 ve 512x512 PNG'ler kayıpsız export edilebilir. Bitmap kaynak (JPEG, düşük çözünürlüklü PNG) kullanıldığında 512x512'ye çıkarmak pikselleşme getirir. Mevcut logonuz yalnızca raster formatta mevcutsa, kaynaktan bağımsız olarak en az 1024x1024 çözünürlükte olmasına dikkat edin; küçültme her zaman büyütmekten daha güvenlidir.
Maskable varyantı ayrıca hazırlamak için pratik yöntem şudur: any ikonunuzu alın, tuvalin her kenarına görselin yüzde onuna karşılık gelen boşluk ekleyin. 192x192 için bu yaklaşık 19px kenar boşluğu anlamına gelir; logoyu ortada 154x154 alana hapseder. Bunu tek seferlik bir Figma bileşeni veya Photoshop template'i olarak kaydedin; ilerleyen rebranding süreçlerinde sadece logo katmanını güncellemek yeter. Ürettiğiniz farklı boyutlardaki PNG dosyaları bu sürecin başlangıç materyali olarak kullanılabilir.
Dosya boyutu genellikle göz ardı edilir. 192x192 PNG için 10-15 KB, 512x512 için 30-50 KB makul aralıklardır. Renk derinliğini sınırlayan flat tasarımlar bu eşiği rahatlıkla karşılar; kompleks fotoğraf tabanlı ikonlar sıkıştırılmadan bu aralığa giremez ve manifest üzerinden yüklenen her ikon dosyası ağ isteği oluşturduğundan gereksiz büyük dosyalar ilk kurulum deneyimini yavaşlatabilir.
Tarayıcı ve cihaz farklılıkları
Chrome, manifest.json'ı en kapsamlı şekilde işleyen tarayıcıdır. purpose, theme_color, background_color ve başlangıç ekranı alanlarının neredeyse tamamını okur. Samsung Internet büyük ölçüde Chrome davranışına yakındır; ancak eski sürümler purpose: maskable alanını işlemez ve tüm ikonları any gibi değerlendirir. Bu durum, maskable varyant için oluşturulmuş ayrı dosyanın o cihazlarda yoksayılması anlamına gelir.
Aynı manifest, farklı sonuç.
Firefox Android, PWA kurulum akışını destekler ancak maskable ikon desteği Chrome kadar tutarlı değildir. Geniş kitleye açık kurumsal uygulamalarda bu fark, tasarım kararlarını etkileyebilir: any ikonun safe zone uyumlu tasarlanması, her tarayıcıda kabul edilebilir görünümü garanti etmenin daha güvenli yoludur.
iOS (Safari) ise manifest.json'daki icons dizisini tamamen görmezden gelir. Ana ekran ikonu için <link rel="apple-touch-icon"> meta etiketiyle 180x180 piksel PNG tanımlanması gerekir. iOS favicon sistemi bu açıdan Android PWA ikonundan bağımsız bir yapıdır; iki platform için ayrı ikon setleri yönetmeniz gerekir. Her ikisi aynı sitede eş zamanlı çalışabilir ama birbirinin yerine geçmez.
Kurulumdan sonra ikon görünmüyorsa
En yaygın neden manifest dosyasının önbellekte kalmasıdır. Chrome, manifest'i her sayfa yüklemesinde yenilemez; arka planda belirli aralıklarla günceller. Uygulamayı kaldırıp yeniden yüklemek çoğu durumda sorunu çözer; ama sorunu sistematik olarak izlemek istiyorsanız DevTools daha kesin sonuç verir.
Chrome DevTools'un Application → Manifest sekmesi, sorunun kaynağını hızla gösterir. Bu sekmede manifest dosyasının okunup okunmadığı, ikon URL'lerinin 200 döndürüp döndürmediği ve tanım hataları açıklamalarıyla listelenir. 404 dönüyorsa src yolu yanlış yazılmıştır. Göreceli yol yerine mutlak yol (/icons/icon-192.png) kullanmak bu tür hataların büyük bölümünü önler; özellikle alt dizinlerdeki sayfalarda göreceli yollar kolayca kırılır.
Bir diğer önemli koşul HTTPS zorunluluğudur. PWA kurulumu yalnızca güvenli bağlantı üzerinden çalışır; localhost geliştirme ortamında istisna tanınır ama canlı ortamda HTTP üzerinden manifest okunan bir site kurulum diyaloğu göstermez. Sitenizin HTTPS durumunu ve sertifika geçerliliğini hızlıca doğrulayabilirsiniz.
Teknik tanımlar doğruysa ama kurulum diyaloğu yine de görünmüyorsa Chrome'un üç temel koşulunu kontrol edin: geçerli manifest, kayıtlı service worker ve HTTPS. Üçü aynı anda sağlanmadan PWA kurulum akışı başlamaz. Service worker kaydını DevTools'un Application → Service Workers sekmesinde, manifest uyumunu ise Lighthouse sekmesindeki PWA denetimiyle doğrulayabilirsiniz. Ikon sorunu bazen yüzeyde görünür ama kökte başka bir koşul eksiktir.