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
- Sol bölmede, Application (Uygulama) altında Manifest'i seçin.
- Tarayıcı tarafından ayrıştırılan manifest alanlarını kontrol edin.
Firefox için
- Denetleyici'yi açın.
- Uygulama sekmesine gidin.
- Sol paneldeki manifest seçeneğini belirleyin.
- 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
veyabrowser
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ındastandalone
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. Gelecektestart_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.
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.
Bu resim, daha fazla dolguyla kullanılabilir hale getirilebilir.
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.
Önerilen alanlar
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.
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.
Ö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çinpt-BR
veya Hintçe içinin
). dir
- Yön yapılabilen manifest alanlarını (ör.
name
,short_name
vedescription
) görüntüleme yönü. Geçerli değerlerauto
,ltr
(soldan sağa) vertl
(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
veyalandscape
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
vesizes
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.