Web uygulaması manifesti

Web uygulaması manifesti, tarayıcıya web içeriğinizin işletim sisteminde uygulama olarak nasıl gösterilmesini istediğinizi belirten bir dosyadır. Manifest; uygulamanın adı, simgesi ve tema rengi gibi temel bilgileri, istenen yön ve uygulama kısayolları gibi gelişmiş tercihleri ve ekran görüntüleri gibi katalog meta verilerini içerebilir.

Her PWA, uygulama başına tek bir manifest içermelidir. Bu manifest genellikle kök klasörde barındırılır ve PWA'nızın yüklenebileceği tüm HTML sayfalarına bağlanır. Resmi uzantısı .webmanifest olduğundan manifest dosyanızı app.webmanifest gibi bir adla adlandırabilirsiniz.

PWA'nıza web uygulaması manifesti ekleme

Web uygulaması manifesti oluşturmak için öncelikle, dize değeri içeren en az bir name alanı içeren bir JSON nesnesi içeren bir metin dosyası oluşturun:

app.webmanifest:

{
   "name": "My First Application"
}

Ancak dosyayı oluşturmak yeterli değildir. Tarayıcının da dosyanın var olduğunu bilmesi gerekir.

Manifestinize bağlantı verme

Tarayıcının web uygulaması manifest'inizi bilmesi için bir <link> HTML öğesi ve PWA'nızın tüm HTML sayfalarında rel özelliğini manifest olarak ayarlayarak manifest'i PWA'nıza bağlamanız gerekir. Bu, bir CSS stil sayfasını dokümana bağlamanıza benzer.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

Manifestte hata ayıklama

Manifest'in doğru şekilde ayarlandığından emin olmak için Firefox'ta İnceleyici'yi ve Chromium tabanlı her tarayıcıda DevTools'u kullanabilirsiniz.

Chromium tarayıcılar için

DevTools'ta

  1. Sol bölmede, Uygulama altında Manifest'i seçin.
  2. Tarayıcının ayrıştırdığı manifest alanlarını kontrol edin.

Firefox için

  1. Denetleyici'yi açın.
  2. Başvuru sekmesine gidin.
  3. Sol panelde Manifest seçeneğini belirleyin.
  4. Tarayıcının ayrıştırdığı manifest alanlarını kontrol edin.

PWA deneyiminizi tasarlama

PWA'nız manifest dosyasına bağlandığında, kullanıcılarınıza sunacağınız deneyimi tanımlamak için alanların geri kalanını doldurmanız gerekir.

Temel alanlar

İlk alan grubu, PWA'nızla ilgili temel bilgileri temsil eder. Bu dosyalar, yüklü PWA'nın simgesini ve penceresini oluşturmak ve nasıl başlatılacağını belirlemek için kullanılır. Bunları şöyle sıralayabiliriz:

name
PWA'nızın tam adı. Bu simge, işletim sisteminin ana ekranında, başlatıcısında, dock'unda veya menüsünde simgeyle birlikte görünür.
short_name
İsteğe bağlı, name alanının tam değerini görüntülemek için yeterli alan olmadığında kullanılan PWA'nızın daha kısa bir adı. Kısaltılma olasılığını en aza indirmek için 12 karakterden kısa tutun.
icons
PWA'yı hangi resimlerin temsil etmesi gerektiğini açıklayan src, type, sizes ve isteğe bağlı purpose alanları içeren simge nesnesi dizisi.
start_url
Kullanıcı, yüklü simgeden PWA'yı başlattığında yüklenecek URL. Mutlak bir yol önerilir. Bu nedenle, PWA'nızın ana sayfası sitenizin köküyse uygulamanız başladığında bu sayfayı açmak için "/" olarak ayarlayabilirsiniz. Başlangıç URL'si sağlamazsanız tarayıcı, PWA'nın yüklendiği URL'yi başlangıç URL'si olarak kullanabilir. Ana ekranınız yerine bir ürünün ayrıntıları gibi derin bir bağlantı olabilir.
display
İşletim sisteminin PWA penceresini nasıl çizmesi gerektiğini açıklayan fullscreen, standalone, minimal-ui veya browser seçeneklerinden biri. Farklı görüntüleme modları hakkında daha fazla bilgiyi Uygulama Tasarımı bölümünde bulabilirsiniz. Çoğu kullanım alanında standalone uygulanır.
id
Bu PWA'yı aynı kaynakta barındırılan diğer uygulamalardan benzersiz şekilde ayırt eden bir dize. Ayarlanmazsa yedek değer olarak start_url kullanılır. Gelecekte start_url değerini değiştirerek (ör. sorgu dizesi değerini değiştirirken) tarayıcının, yüklü bir PWA'yı algılama özelliğini kaldırabileceğinizi unutmayın.

Simgeler

PWA'nızın simgesi, uygulama yüklendiğinde kullanıcılarınızın cihazlarındaki görsel kimliğidir. Bu nedenle, en az bir simge tanımlamanız önemlidir. icons mülkü bir simge nesnesi koleksiyonudur. Bu nedenle, kullanıcılarınıza en iyi simge deneyimini sunmak için farklı biçimlerde çeşitli simgeler tanımlayabilirsiniz. Her tarayıcı, ihtiyaçlarına ve yüklü olduğu işletim sistemine göre bir veya daha fazla simge seçer. Bu simgeler, gerekli özelliklere daha yakındır.

Yalnızca bir simge boyutu seçmeniz gerekiyorsa bu boyut 512x512 piksel olmalıdır. Ancak 192x192, 384x384 ve 1024x1024 piksel boyutlarında resimler de dahil olmak üzere daha fazla boyut sağlamanız önerilir.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

Simge sağlamazsanız veya simgeler önerilen boyutlarda değilse bazı platformlarda yükleme ölçütlerini geçemezsiniz. Diğer platformlarda simge, örneğin PWA'nın ekran görüntüsünden veya genel bir simge kullanılarak otomatik olarak oluşturulur.

Maskelenebilir simgeler

Android gibi bazı işletim sistemleri, simgeleri farklı boyutlara ve şekillere uyarlar. Örneğin, Android 12'de farklı üreticiler veya ayarlar, simgelerin şeklini dairelerden karelere veya yuvarlatılmış köşeli karelere değiştirebilir. Bu tür uyarlanabilir simgeleri desteklemek için purpose alanını kullanarak maskelenebilir bir simge sağlayabilirsiniz.

Bunun için ana simgesi "güvenli bölge" içinde bulunan bir kare resim dosyası gönderin. Güvenli bölge, simgenin ortasına yerleştirilmiş ve yarıçapı simgenin genişliğinin yüzde 40'ı olan bir dairedir. (Aşağıdaki resme bakın.) Maskelenebilir simgeleri destekleyen cihazlar, simgenizi gerektiği gibi maskeler.

Kare simge içinde yüzde 40 yarıçaplı merkezlenmiş daire olarak işaretlenen güvenli alan

Aşağıda, yaygın olarak kullanılan çeşitli şekillerde oluşturulmuş maskelenebilir bir simge örneği verilmiştir:

Aşağıdaki resimde, sol taraftaki simgeyi maskelenebilir simge olarak kullanırsanız cihazlara şekil maskesi uygulandığında kötü sonuçlar elde edersiniz.

Maskelenebilir simge için uygun olmayan bir simge.

Bu resim, daha fazla dolguyla kullanılabilir hale getirilebilir.

Daha fazla dolguya sahip simge maskeler için uygundur.

Maskelenebilir simgeler en az 512x512 boyutunda olmalıdır. Oluşturduğunuz icons koleksiyonunu, desteklenen cihazlarda deneyimi iyileştirmek için ekleyebilirsiniz:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

Maskelenebilir simgeniz çoğu durumda iyi görünmüyorsa daha fazla dolgu ekleyerek simgeyi iyileştirebilirsiniz. Maskable.app, simgenizin maskelenebilir bir sürümünü test etmek ve oluşturmak için kullanabileceğiniz ücretsiz bir online araçtır.

Simgeniz genel ve maskelenebilir amaçlar için kullanılıyorsa purpose alanını "any maskable" olarak ayarlayabilirsiniz. Ayrıntılar için MDN Web Uygulaması Manifesti dokümanlarına bakın.

Eklenecek bir sonraki alan grubu, yüklenebilme için gerekli olmasa da kullanıcınızın deneyimini iyileştirecek olanlardır.

theme_color
Uygulamanın varsayılan rengi. Bazen işletim sisteminin siteyi nasıl görüntülediğini etkiler (ör. masaüstünde pencere ve başlık çubuğu rengi veya mobil cihazlarda durum çubuğu rengi). Bu renk, HTML theme-color <meta> öğesi tarafından geçersiz kılınabilir.
background_color
Uygulamanın stil sayfası yüklenmeden önce uygulamanın arka planında gösterilecek yer tutucu rengi. iOS ve iPadOS'teki Safari ve çoğu masaüstü tarayıcısı şu anda bu alanı yoksaymaktadır.
scope
Yüklü uygulamanın penceresinde nelerin gösterileceğini ve nelerin gösterilmeyeceğini tanımlamanıza olanak tanıyarak PWA'nın gezinme kapsamını değiştirir. Örneğin, kapsamın dışındaki bir sayfaya bağlantı verirseniz bu sayfa, PWA pencerenizde değil, uygulama içi bir tarayıcıda oluşturulur. Ancak bu, hizmet işleyicinizin kapsamını değiştirmez.

Aşağıdaki resimde, bir PWA'yı yüklediğinizde theme_color alanının masaüstü cihazdaki başlık çubuğu için nasıl kullanıldığı gösterilmektedir.

Masaüstüne farklı tema rengiyle yüklenen aynı PWA.

Manifestte renkleri tanımlarken (ör. theme_color ve background_color içinde) salmon veya orange gibi CSS adlandırılmış renkleri, #FF5500 gibi RGB renkleri veya rgb() ya da hsl() gibi saydamlık içermeyen renk işlevlerini kullanmanız gerekir. Daha fazla bilgi için Uygulama tasarımı bölümünü inceleyin.

Dene

Başlangıç ekranları

Bazı cihazlarda, kullanıcıya anında geri bildirim sağlamak için PWA'nız yüklenirken statik bir resim oluşturulur.

Android, başlangıç ekranını oluşturmak için theme_color, background_color ve icon değerlerini kullanır.

Android'e bir PWA yüklediğinizde cihaz, aşağıdaki şemada gösterildiği gibi manifest dosyanızdan alınan bilgileri içeren bir açılış ekranı oluşturur.

Android açılış ekranında, manifest&#39;ten farklı değerler alan bir PWA.

Öte yandan iOS ve iPadOS'teki Safari, açılış ekranları oluşturmak için web uygulaması manifest'ini kullanmaz. Bunun yerine, simgelerle işleme benzer şekilde özel bir <link> öğesinden bağlantı verilen bir resim kullanırlar. Daha fazla bilgi için Geliştirme bölümünü inceleyin.

Genişletilmiş alanlar

Sonraki alan grubu, PWA'nız hakkında ek bilgiler sağlar. Bunların tümü isteğe bağlıdır.

lang
Manifestin değerlerinin birincil dilini belirten bir dil etiketi (ör. İngilizce için en, Brezilya Portekizcesi için pt-BR veya Hintçe için in).
dir
Yön özelliğine sahip manifest alanlarının (name, short_name ve description gibi) gösterileceği yön. Geçerli değerler auto, ltr (soldan sağa) ve rtl (sağdan sola) şeklindedir.
orientation
Yüklendikten sonra uygulamanın istenen yönü. Bir oyun, bu ayarı yalnızca yatay yön isteyecek şekilde ayarlayabilir. Çeşitli değerler kabul edilir ancak dahil edilirse genellikle açıkça portrait veya landscape olur.

Tanıtım alanları

Dördüncü alan grubu, PWA'nızla ilgili tanıtım amaçlı bilgileri (ör. yükleme akışlarında, listelemelerde ve arama sonuçlarında) sağlamanıza olanak tanır.

description
PWA'nın işlevini açıklayan bir açıklama.
screenshots
PWA'yı sergilemek için src, type ve sizes (icons nesnesine benzer) içeren ekran görüntüsü nesnesi dizisi. Boyut kısıtlaması yoktur.
categories
PWA'nın, girişler için ipucu olarak kullanılmak üzere ait olması gereken kategori dizisi (isteğe bağlı olarak bilinen kategoriler listesinden). Bu değerler genellikle küçük harflidir.
iarc_rating_id
Varsa PWA için Uluslararası Yaş Derecelendirme Birliği sertifika kodu. Bu bilgi, PWA'nızın hangi yaş grupları için uygun olduğunu belirlemek amacıyla kullanılır.

Bu promosyon alanlarını hemen kullanmaya başlayabilirsiniz. Örneğin, Android'de PWA'nız yüklenebilir durumdaysa ve en azından description ve screenshots alanları için değer sağlarsanız yükleme iletişim kutusu deneyimi, basit bir "Ana ekrana ekle" bilgi çubuğundan uygulama mağazasındakine benzer daha zengin bir yükleme iletişim kutusuna dönüşür.

Android'de, tanıtım alanları için değerler sağlarsanız daha güzel bir yükleme kullanıcı arayüzü elde edebilirsiniz. Bunu aşağıdaki videoda görebilirsiniz.

Aşağıdaki promosyon alanlarının nasıl çalıştığını görün:

Özellikler Alanları

Son olarak, PWA'nızın desteklenen tarayıcılarda kullanabileceği farklı özelliklerle ilgili çeşitli alanlar vardır. Örneğin, Özellikler bölümünde ele aldığımız shortcuts, share_target, display_override alanları bu tür alanlara örnek gösterilebilir. Ayrıca, PWA'nızı genellikle bir uygulama mağazasından yüklü uygulamalara bağlamak için related_apps ve prefer_related_apps gibi alanlar da vardır (daha fazla bilgi için Algılama bölümüne bakın).

Tarayıcılar Progresif Web Uygulamalarına daha fazla özellik ekledikçe gelecekte birçok yeni alan görünebilir.

Kaynaklar