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 Chromium tabanlı her tarayıcıda Firefox ve Geliştirici Araçları'nda Denetleyici'yi kullanabilirsiniz.

Chromium tarayıcılar için

Geliştirici Araçları'nda

  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
Hangi resimlerin PWA'yı temsil etmesi gerektiğini açıklayan, src, type, sizes ve isteğe bağlı purpose alanları olan simge nesneleri dizisi.
start_url
Kullanıcı, yüklü simgeden PWA'yı tıkladığında PWA'nın yüklemesi gereken 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ılabilen diğer uygulamalarla benzersiz şekilde tanımlayan 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 boyutunda 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 karşılayamazsınız. 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.

Bunu yapmak için ana simgesini "güvenli bölge"nin içine yerleştirdiğiniz bir kare resim dosyası sağlayın. 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ğinde 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, soldaki simgeyi maskelenebilir simge olarak kullanırsanız cihazlarda şekil maskesi uygulandığında kötü sonuçlar alırsınız.

Maskelenebilir simge için uygun olmayan bir simge.

Bu resim, daha fazla dolgu eklenerek kullanılabilir hale getirilebilir.

Daha fazla dolgulu 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 iyileştirebilirsiniz. Maskable.app, simgenizin maskelenebilir bir sürümünü test edip oluşturmak için kullanabileceğiniz ücretsiz bir online araçtır.

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
Stil sayfası yüklenmeden önce uygulamanın arka planında görüntülenecek yer tutucu rengi. iOS ve iPadOS'teki Safari ile ç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 pencereniz yerine uygulama içi tarayıcıda oluşturulur. Ancak bu, hizmet çalışanınızın kapsamını değiştirmez.

Sonraki resimde, PWA yüklediğinizde masaüstü cihazda başlık çubuğu için theme_color alanının 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 PWA yüklediğinizde cihaz, aşağıdaki şemada gösterildiği gibi manifest dosyanızdan gelen bilgileri içeren bir başlangıç ekranı oluşturur.

Android başlangıç 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ı manifestini kullanmaz. Bunun yerine, simgelerin işlenme biçimine 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 sunar. 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. Birkaç değer kabul edilir, ancak dahil edilmesi durumunda genellikle açıkça portrait veya landscape kullanılır.

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. PWA'nızın hangi yaşlar için uygun olduğunu belirlemek amacıyla kullanılmak üzere tasarlanmıştır.

Bu promosyon alanlarını hemen kullanmaya başlayabilirsiniz. Örneğin, Android'de PWA'nız yüklenebilir durumdaysa ve en azından description ile screenshots alanları için değer giriyorsanı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.

Bu tanıtım alanlarının nasıl çalıştığını görün:

Özellikler Alanları

Son olarak, Özellikler bölümünde ele aldığımız shortcuts, share_target, display_override alanları gibi PWA'nızın desteklenen tarayıcılarda kullanabileceği farklı özelliklerle ilgili bir dizi alan bulunur. PWA'nızı yüklü uygulamalara (genellikle bir uygulama mağazasından) bağlamak için related_apps ve prefer_related_apps (daha fazla bilgi için Algılama bölümüne bakın) gibi alanlar da bulunur.

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

Kaynaklar