Web uygulaması manifesti

Web uygulaması manifest dosyası, oluşturduğunuz bir dosyadır ve tarayıcıya, web içeriğinizin işletim sisteminde uygulama olarak nasıl görünmesini istediğinizi bildirir. Manifest'te uygulamanın adı, simgesi ve tema rengi gibi temel bilgiler; istenen yön ve uygulama kısayolları gibi gelişmiş tercihler ve ekran görüntüleri gibi katalog meta verileri yer alabilir.

Her PWA, her uygulama için genellikle kök klasörde barındırılan ve PWA'nızın yüklenebileceği tüm HTML sayfalarında bağlantı verilen tek bir manifest içermelidir. Resmi uzantısı .webmanifest olduğundan manifest dosyanıza app.webmanifest gibi bir ad verebilirsiniz.

PWA'nıza web uygulaması manifesti ekleme

Bir web uygulaması manifest dosyası oluşturmak için ilk olarak, dize değeri içeren en az bir name alanı içeren JSON nesnesiyle 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.

Manifest dosyanıza bağlantı oluşturma

Tarayıcının web uygulaması manifestinizden haberdar olması için bunu bir <link> HTML öğesi ve tüm PWA'nızın HTML sayfalarında manifest olarak ayarlanmış rel özelliği kullanarak PWA'nıza bağlamanız gerekir. Bu, bir CSS stil sayfasını bir dokümana bağlamanıza benzer.

index.html:

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

Manifest'te hata ayıklama

Manifest'in doğru şekilde ayarlandığından emin olmak için Chromium tabanlı her tarayıcıda Firefox'u ve Geliştirici Araçları'nı kullanabilirsiniz.

Chromium tarayıcılar için

Geliştirici Araçları'nda

  1. Sol bölmede, Application (Uygulama) altında Manifest'i seçin.
  2. Tarayıcı tarafından ayrıştırılan manifest alanlarını kontrol edin.

Firefox için

  1. Denetleyici'yi açın.
  2. Uygulama sekmesine gidin.
  3. Sol paneldeki manifest seçeneğini belirleyin.
  4. Tarayıcı tarafından ayrıştırılan manifest alanlarını kontrol edin.

PWA deneyiminizi tasarlama

PWA'nız artık manifest dosyasına bağlandığından, kullanıcılarınıza yönelik deneyimi tanımlamak üzere diğer alanları doldurmanın zamanı gelmiştir.

Temel alanlar

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

name
PWA'nızın tam adı. İşletim sisteminin ana ekranı, başlatıcı, yuva veya menü simgesiyle birlikte görünür.
short_name
İsteğe bağlı. PWA'nızın, name alanının tam değerini göstermek için yeterli alan olmadığında kullanılacak daha kısa bir adı. Kısaltma olasılığını en aza indirmek için metni 12 karakterden kısa tutun.
icons
src, type, sizes ve isteğe bağlı purpose alanları içeren ve hangi resimlerin PWA'yı temsil etmesi gerektiğini açıklayan simge nesneleri dizisi.
start_url
PWA'nın kullanıcı tarafından yüklenen simgeden başlattığında yüklenmesi gereken URL. Mutlak yol önerilir. Bu nedenle, PWA'nızın ana sayfası sitenizin köküyse uygulamanız başladığında açmak için bunu "/" olarak ayarlayabilirsiniz. Başlangıç URL'si sağlamazsanız tarayıcı başlangıç olarak PWA'nın yüklendiği URL'yi kullanabilir. Bu bağlantı, ana ekranınız yerine bir ürünün ayrıntıları gibi derin bağlantı olabilir.
display
İşletim sisteminin PWA penceresini nasıl çizmesi gerektiğini açıklayan fullscreen, standalone, minimal-ui veya browser değerlerinden biri. Uygulama Tasarımı bölümünde farklı görüntü modları hakkında daha fazla bilgi edinebilirsiniz. Çoğu kullanım alanında standalone uygulanır.
id
PWA'yı aynı kaynakta barındırılmış olabilecek diğer PWA'larla benzersiz şekilde tanımlayan bir dizedir. Ayarlanmazsa start_url, yedek değer olarak kullanılır. Gelecekte start_url özelliğini değiştirdiğinizde (örneğin sorgu dizesi değerini değiştirdiğinizde), tarayıcının PWA'nın zaten yüklü olup olmadığını algılama yeteneğini kaldırabileceğinizi unutmayın.

Simgeler

PWA'nızın simgesi, kullanıcılarınızın cihazlarında yüklü olan görsel kimliğidir. Bu nedenle en az bir tane tanımlamanız önemlidir. icons özelliği simge nesnelerinden oluşan bir koleksiyon olduğundan, kullanıcılarınıza en iyi simge deneyimini sağlamak için farklı biçimlerde birkaç simge tanımlayabilirsiniz. Her tarayıcı, ihtiyaçlarına ve yüklü işletim sistemine bağlı olarak bir veya daha fazla simge seçer. Simgeler, gereken özelliklere daha yakındır.

Yalnızca bir simge boyutu seçmeniz gerekiyorsa boyut 512x512 piksel olmalıdır. Ancak, 192x192, 384x384 ve 1024x1024 piksel boyutlu 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ı boyut ve şekillere uyarlar. Örneğin, Android 12'de farklı üreticiler veya ayarlar, simgelerin şeklini, dairelerden karelere, yuvarlak köşeli karelere çevirebilir. Bu tür uyarlanabilir simgeleri desteklemek için purpose alanını kullanarak maskelenebilir bir simge sağlayabilirsiniz.

Bunun için, ana simgesinin "güvenli bölge" içinde bulunduğu, simgenin merkezinde bulunan ve simge genişliğinin %40'ını oluşturan bir dairenin bulunduğu kare bir resim dosyası sağlayın. (Aşağıdaki resmi inceleyin.) Maskelenebilir simgeleri destekleyen cihazlar simgenizi gereken şekilde maskeler.

Kare simge içinde yüzde 40 yarıçapında ortalanmış daire olarak işaretlenmiş güvenli alan

Yaygın olarak kullanılan pek çok şekilde oluşturulan maskelenebilir simgeye bir örnek aşağıda verilmiştir:

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

Maskelenebilir bir 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 512 x 512 boyutunda olmalıdır. Oluşturulan bir cihazı icons koleksiyonunuza ekleyerek desteklenen cihazların deneyimini iyileştirebilirsiniz:

"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 iyi görüntülenmiyorsa çoğu durumda daha fazla dolgu ekleyerek simgenizi iyileştirebilirsiniz. Maskable.app, simgenizin maskelenebilir sürümünü test etmek ve oluşturmak için kullanabileceğiniz ücretsiz bir online araçtır.

Eklenecek bir sonraki alan grubu, yüklenebilirlik için gerekli olmasa da kullanıcı deneyimini iyileştirecek alanlardır.

theme_color
Uygulama için varsayılan renktir ve bazen işletim sisteminin siteyi görüntüleme biçimini etkiler (örneğin, masaüstünde pencere ve başlık çubuğunun rengi veya mobil cihazlarda durum çubuğunun 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österilecek yer tutucu rengi. iOS ile iPadOS'teki Safari uygulaması ve çoğu masaüstü tarayıcısı şu anda bu alanı yoksaymaktadır.
scope
PWA'nın gezinme kapsamını değiştirerek yüklü uygulamanın penceresinde nelerin gösterilip gösterilmeyeceğini tanımlayabilirsiniz. Örneğin, kapsam dışında kalan 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ü cihazdaki başlık çubuğu için theme_color alanının nasıl kullanıldığı gösterilmektedir.

Aynı PWA masaüstüne farklı bir tema rengiyle yüklendi.

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

Deneyin

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 alınan 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, başlangıç ekranı oluşturmak için web uygulaması manifestini kullanmaz. Bunun yerine, simgelerin işlenme şekline benzer şekilde özel bir <link> öğesinden bağlantı verilen bir resim kullanırlar. Daha fazla ayrıntı için Geliştirme bölümüne göz atın.

Genişletilmiş alanlar

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

lang
Manifest 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 yapılabilen manifest alanlarını (ör. name, short_name ve description) görüntüleme yönü. Geçerli değerler auto, ltr (soldan sağa) ve rtl (sağdan sola) değerleridir.
orientation
Yüklendikten sonra uygulama için istenen yön. Bir oyun bunu yalnızca yatay yön istemek için ayarlayabilir. Birkaç değer kabul edilir, ancak eklenirse genellikle açık bir şekilde portrait veya landscape olur.

Promosyon alanları

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

description
PWA'nın işleviyle ilgili açıklama.
screenshots
PWA'yı göstermesi amaçlanan, src, type ve sizes içeren ekran görüntüsü nesneleri dizisi (icons nesnesine benzer). Boyut kısıtlaması yoktur.
categories
PWA'nın ait olması gereken kategori dizisi, girişler için ipucu olarak kullanılmalıdır (isteğe bağlı olarak bilinen kategoriler listesinden). Bu değerler genellikle küçük harfle yazılır.
iarc_rating_id
PWA için Uluslararası Yaş Derecelendirme Birliği sertifika kodu (varsa). PWA'nızın hangi yaşlar için uygun olduğunu belirlemek amacıyla kullanılması amaçlanmıştır.

Bu promosyon alanlarını uygulamalı olarak görebilirsiniz. Örneğin, Android'de PWA'nız yüklenebilir ise ve en azından description ile 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.

Bir sonraki videoda görebileceğiniz gibi, Android'de tanıtım alanları için değerler sağlarsanız daha iyi bir yükleme kullanıcı arayüzü elde edebilirsiniz

Aşağıdaki promosyon 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 ve display_overrides alanları gibi PWA'nızın desteklenen tarayıcılarda kullanabileceği farklı özelliklerle ilgili bir dizi alan bulunur. 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 ekleyecekken, birçok yeni alanla karşılaşabilirsiniz.

Kaynaklar