Web Uygulaması Bildirim Kılavuzu
Web uygulaması bildirimi (site.webmanifest), yüklenebilir tarayıcılara uygulamanızın adını, renklerini, görüntüleme modunu ve ana ekranda hangi simge boyutlarının kullanılacağını bildiren bir JSON dosyasıdır. Bunu "<link rel='manifest' href='/site.webmanifest'>" ile bağlamak, masaüstünde ve Android'te Chrome ve Edge PWA yükleme istemini etkinleştirir. Eksiksiz bir PWA favicon kurulumu için, her ikisi de favicon generator tarafından dışa aktarılan 192×192 ve 512×512 PNG simgeleriyle eşleştirin.
Web uygulaması bildirimi, `application/manifest+json` MIME türüyle sunulan bir JSON metin dosyasıdır. Seçtiğiniz herhangi bir URL'de bulunur, ancak alan adı kökünde kural /site.webmanifest'tir. Bunu, `<head>` öğesinin içindeki `<link rel='manifest' href='/site.webmanifest'>` kullanarak HTML'inizden bağlarsınız. Tarayıcı, bir yükleme isteminin gösterilip gösterilmeyeceğini veya uygulamanızı yüklemeden sonra nasıl oluşturacağını değerlendirirken bildirimi okur.
Simgeler dizisi manifestin favicon ile en alakalı kısmıdır. Her giriş bir src (görüntünün URL'si), boyutları (piksel boyutları), türü (MIME türü) ve isteğe bağlı olarak amacı ('herhangi bir', 'maskelenebilir' veya 'herhangi bir maskelenebilir') belirtir. Başlatıcı simgesi için en azından 192×192 PNG ve açılış ekranı için 512×512 PNG sağlayın. Bunlar olmadan Chrome bir yükleme istemi göstermez.
192×192 simgesi, PWA'iniz bir web push bildirimi gönderdiğinde uygulama başlatıcıda, son uygulamalar değiştiricide ve bildirim gölgesinde Android Chrome tarafından kullanılır. Bir PNG olmalı, beyan edilen URL'sinden yönlendirmeler olmadan erişilebilir olmalı ve bildiriminizden farklı bir alandaysa uygun CORS üstbilgileriyle sunulmalıdır. favicon generator, doğrudan kullanıma hazır şekilde android-chrome-192x192.png dosyasını dışa aktarır.
512×512 simgesi, uygulama ana ekranda başlatıldıktan sonra yüklenirken gösterilen PWA açılış ekranı, masaüstündeki Chrome ve Edge'teki yükleme iletişim kutusu önizlemesi ve Chrome İşletim Sistemi uygulama başlatıcısı için kullanılır. Bildirimde eksik bir 512×512 girişi kurulumu engellemez ancak açılış ekranında genel bir tarayıcı simgesinin ortaya çıkmasına neden olur. Gösterişli bir kurulum deneyimi için her zaman bunu ekleyin.
Maskelenebilir simgeler Android'e özgü bir geliştirmedir. Android uyarlanabilir simge sistemi, uygulama simgelerine geometrik maskeler (daire, sincap, gözyaşı damlası, yuvarlak köşeli dikdörtgen) uygular ve şekil, cihaz üreticisine göre değişir. Standart bir 'herhangi bir' simgenin kenarları bu maskeler tarafından kırpılmış olabilir. 'Maskelenebilir' simge, güvenli bölge dolgusu içerir; temel sanat eserini görüntünün %80'inin ortasında (güvenli bölge dairesi) tutun; böylece herhangi bir maske, logoyu kırpmadan uygulanabilir.
Manifest'te maskelenebilir bir simge bildirmek için aynı boyutta `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }` ile ikinci bir giriş ekleyin. Ayrıca şunları da birleştirebilirsiniz: `'purpose': 'any maskable'`'i tek bir girişte. Oluşturucunun maskelenebilir dışa aktarma seçeneğini kullanarak maskelenebilir simgenizi ekstra dolguyla oluşturun.
Ad ve short_name alanları, uygulamanızın ana ekranda ve uygulama çekmecesinde nasıl etiketlendiğini kontrol eder. `name`, yükleme istemi sırasında gösterilen uygulamanın tam adıdır. `short_name`, ana ekrandaki simgenin altındaki etikettir; daha küçük ekranlarda kesilmesini önlemek için onu 12 karakterden kısa tutun. Kurulum isteminin görünmesi için her iki alan da gereklidir.
theme_color alanı, kullanıcı sitenize gittiğinde (yalnızca PWA yüklendiğinde değil) Android Chrome üzerindeki tarayıcı adres çubuğunun rengini ayarlar. Ayrıca bağımsız PWA modunda araç çubuğu rengini de ayarlar. Ana marka renginizi onaltılık değer olarak kullanın. Manifest'in theme_color değerini okumayan tarayıcılar için HTML'inize eşleşen bir "<meta name='theme-color' content='#YOUR_COLOR'>" ekleyin.
arka plan_rengi alanı, PWA'in başlatılması ile uygulama içeriğinizin ilk boyası arasında gösterilen açılış ekranı arka plan rengini kontrol eder. Sarsıcı bir flaşı önlemek için bunu uygulamanızın arka planına (genellikle beyaz veya ana marka rengine) uyacak şekilde ayarlayın. Arka plan_rengi gerçek uygulama arka planınızla eşleşmiyorsa kullanıcılar başlatma sırasında bir renk atlaması görür.
Görüntüleme alanı, kurulumdan sonra PWA'in nasıl görüneceğini belirler. `standalone`, tarayıcının adres çubuğunu ve gezinme düğmelerini gizleyerek uygulamanın yerel bir uygulama gibi görünmesini sağlar. `minimal-ui` minimum gezinme çubuğunu korur. `fullscreen`, durum çubuğu dahil her şeyi kaldırır. `browser` tam tarayıcı kullanıcı arayüzünü gösterir. Çoğu PWA için `standalone` doğru seçimdir. Ekran `browser` olarak ayarlanmışsa kurulum istemi görünmez.
start_url alanı, kullanıcı yüklü PWA'i ana ekrandan başlattığında hangi URL'nin açılacağını belirtir. Her zaman bunu ekleyin; bu olmadan Android, manifestin keşfedildiği URL'yi açar; bu, ana sayfanız yerine bir derin bağlantı sayfası olabilir. Çoğu site için `'start_url': '/'`'i veya uygulamanızın belirli bir rotadan başlaması gerekiyorsa belirli bir URL'yi kullanın.
Chrome DevTools'ta bildirim sorunlarının hatalarını ayıklamak basittir. DevTools'u (F12) açın, Uygulama sekmesine gidin ve sol paneldeki Manifest'e tıklayın. Chrome, bildiriminizin ayrıştırılmış bir görünümünü, tüm ayrıştırma hatalarını, simge getirme hatalarını ve yükleme isteminin neden gösterilmediğini açıklayan bir 'Yüklenebilirlik' kontrol listesini gösterir. Yaygın sorunlar arasında simgelerin bulunamaması (404), yanlış MIME türü veya eksik 192×192 simge yer alır.
Bildirinin doğru şekilde sunulması, iki sunucu tarafı yapılandırmasını gerektirir. Öncelikle dosyanın `Content-Type: application/manifest+json` ile sunulması gerekir. İkinci olarak, simgeleriniz bir CDN'deyse veya bildirimden farklı bir kaynaktaysa simge yanıtları uygun CORS başlıklarını (`Access-Control-Allow-Origin: *` veya alanınız) içermelidir. Simge dosyalarındaki eksik CORS üstbilgileri, tarayıcının bildirimi geçersiz olarak değerlendirmesine neden olur.
Bildirimi otomatik olarak oluşturan çerçeveler için, oluşturulan dosyanın gerçek simge boyutlarınızı ve renklerinizi içerdiğini doğrulayın. Next.js, /app/manifest.ts dışa aktarmanızdan bir bildirim oluşturur. React Oluştur Uygulaması bir /public/manifest.json oluşturur. Vite varsayılan olarak bir bildirim oluşturmaz; manuel olarak bir bildirim oluşturun. Her durumda, simgeler dizisini, varsayılan yer tutucu simgeler yerine gerçek markalı simge dosyalarınıza referans verecek şekilde güncelleyin.
Nasıl çalışır
- 1
192×192 ve 512×512 PNG simgeleri oluşturun
512×512 logonuz PNG veya SVG'i [favicon generator](tool:favicon-generator)'e yükleyin. İndirme paketi, doğrudan kullanıma hazır android-chrome-192x192.png ve android-chrome-512x512.png'yi içerir.
- 2
site.webmanifest'i oluştur
En az şunu içeren bir JSON dosyası oluşturun: `name`, `short_name`, `icons` (192 ve 512 giriş), `theme_color`, `background_color` ve `display: 'standalone'`. Oluşturucu paketi önceden doldurulmuş bir bildirim şablonu içerir.
- 3
Manifest'i doğru MIME türüyle sunun
Sunucunuzu `Content-Type: application/manifest+json` ile .webmanifest dosyalarını sunacak şekilde yapılandırın. Apache'de .htaccess'e `AddType application/manifest+json .webmanifest` ekleyin. Nginx'te MIME türünü mime.types'e ekleyin.
- 4
Manifest'i HTML'e bağlayın
`<head>` dosyanızın içine `<link rel='manifest' href='/site.webmanifest'>` ekleyin. Ayrıca manifest theme_color'u okumayan tarayıcılar için "<meta name='theme-color' content='#YOUR_COLOR'>" ekleyin.
- 5
Chrome DevTools ile doğrulayın
Chrome DevTools > Uygulama > Manifest'i açın. Hiçbir hatanın gösterilmediğini ve tüm simgelerin çözüldüğünü doğrulayın. PWA kurulum isteminin tam olarak karşılanan veya karşılanmayan kriterleri için Yüklenebilirlik bölümünü kontrol edin.
- 6
Yükleme istemini test edin
Android Chrome'te sitenize gidin. Tüm kriterler karşılanırsa Chrome, tarayıcı menüsünde bir yükleme başlığı veya 'Ana Ekrana Ekle' seçeneğini gösterir. Kurulumdan sonra açılış ekranı arka plan renginin ve ana ekran simgesinin doğru şekilde oluşturulduğunu doğrulayın.
Hemen deneyin
PWA simge paketinizi oluşturun
Favicon OluşturucuSSS
Temel bir web sitesi için bir web uygulaması bildirimi gerekli midir?+
Hayır — yalnızca Android ve masaüstü Chrome/Edge üzerinde PWA ana ekrana yükleme istemini istiyorsanız. favicon.ico tek başına tarayıcı sekmelerini yönetir. Daha zengin mobil ve masaüstü yükleme deneyimlerini etkinleştirmek istediğinizde bildirimi ekleyin.
Web uygulaması bildiriminde hangi simge boyutları bulunur?+
Minimum: 192×192 (Android başlatıcı) ve 512×512 (açılış ekranı ve kurulum önizlemesi). Uyarlanabilir Android simge desteği için her iki boyutun ve ek yoğunluk kapsamı istiyorsanız 384×384'ün maskelenebilir çeşitlerini ekleyin.
Bildiride tema_rengi ile arka plan_rengi arasındaki fark nedir?+
theme_color tarayıcı adres çubuğunu ve araç çubuğu rengini ayarlar. arka plan_rengi, uygulamanızın ilk boyamasından önce gösterilen açılış ekranı arka plan rengini ayarlar. Sorunsuz bir yükleme ve başlatma deneyimi için her ikisini de markanıza uyacak şekilde ayarlayın.
Chrome neden PWA cihazım için bir yükleme istemi göstermiyor?+
En yaygın nedenler şunlardır: eksik veya geçersiz bildirim, eksik 192×192 simge, 404 döndüren simgeler, bildirimin doğru MIME türüyle sunulmaması veya sitenin HTTPS üzerinden sunulmaması. Yüklenebilirlik hatasının tam nedenini görmek için Chrome DevTools > Uygulama > Bildirim'i kullanın.
Maskelenebilir simge nedir ve buna ihtiyacım var mı?+
Maskelenebilir bir simge, güvenli bölge dolgusu içerir; böylece Android, logonuzu kırpmadan dairesel veya kıvrımlı maskeler uygulayabilir. Kare olmayan uyarlanabilir simge şekilleri kullanan Android cihazlarda ana ekran simgenizin doğru görünmesi için bir simgeye ihtiyacınız vardır. Bildirim simgeleri dizisinde bunu `'purpose': 'maskable'` ile bildirin.
Web uygulaması bildiriminde SVG simgelerini kullanabilir miyim?+
Chromium, bazı bildirim simgesi bağlamlarında SVG'i destekler, ancak PNG, tarayıcılar arası yükleme kullanıcı arayüzleri için evrensel olarak güvenli varsayılandır. Her zaman PNG 192 ve 512 girişlerini ekleyin. Hiçbir zarar vermeden yanlarına SVG girişi ekleyebilirsiniz.
Web bildirimimin geçerli olup olmadığını nasıl kontrol ederim?+
Chrome DevTools (F12) > Uygulama > Bildirim'i açın. Chrome ayrıştırma hatalarını, simge getirme hatalarını ve eksiksiz bir kurulabilirlik kontrol listesini gösterir. Bildirilen sorunları düzeltin, ardından Chrome'in adres çubuğundaki 'Ana Ekrana Ekle' seçeneğini kullanarak yükleme istemini yeniden test edin.