Web uygulaması manifesti, tarayıcıya Progresif Web Uygulamanızın (PWA) kullanıcının masaüstü veya mobil cihazına yüklendiğinde nasıl davranması gerektiğini bildiren bir JSON dosyasıdır. Tipik bir manifest dosyası en azından şunları içerir:
- Uygulamanın adı
- Uygulamanın kullanması gereken simgeler
- Uygulama başlatıldığında açılması gereken URL
Manifest dosyasını oluşturma
Manifest dosyasının herhangi bir adı olabilir, ancak genellikle manifest.json
olarak adlandırılır ve kökten (web sitenizin üst düzey dizini) sunulur. Spesifikasyon, uzantının .webmanifest
olması gerektiğini belirtiyor, ancak manifest'lerinizin daha kolay okunmasını sağlamak için JSON dosyalarını kullanmak isteyebilirsiniz.
Tipik bir manifest şöyle gör��n��r:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
Temel manifest özellikleri
short_name
ve name
Manifest'inizde en az bir short_name
veya name
sağlamalısınız. Her ikisini de sağlarsanız uygulama yüklendiğinde name
, kullanıcının ana ekranı, başlatıcısı veya alanın sınırlı olduğu diğer yerlerde short_name
kullanılır.
icons
Bir kullanıcı PWA'nızı yüklediğinde, tarayıcı için ana ekranda, uygulama başlatıcıda, görev değiştiricide, başlangıç ekranında ve diğer yerlerde kullanılacak bir dizi simge tanımlayabilirsiniz.
icons
özelliği, görüntü nesneleri dizisidir. Her nesne resmin src
, sizes
ve type
özelliğini içermelidir. Android'de uyarlanabilir simge olarak da bilinen maskelenebilir simgeleri kullanmak için icon
özelliğine "purpose": "any maskable"
ekleyin.
Chromium için en az 192x192 piksel simge ve 512x512 piksel simge sağlamanız gerekir. Yalnızca bu iki simge boyutu sağlanırsa Chrome, simgeleri cihaza sığacak şekilde otomatik olarak ölçeklendirir. Kendi simgelerinizi ölçeklendirmeyi ve piksel mükemmelliği için ayarlamayı tercih ederseniz simgeleri 48 dp'lik artışlarla sağlayın.
id
id
özelliği, uygulamanız için kullanılan tanımlayıcıyı açık bir şekilde tanımlamanıza olanak tanır. id
özelliğini manifest dosyasına eklemek, start_url
öğesine veya manifest'in konumuna olan bağımlılığı ortadan kaldırır ve bunların ileride güncellenmesine olanak tanır. Daha fazla bilgi için PWA'ları web uygulaması manifest kimliği mülküyle benzersiz şekilde tanımlama bölümüne bakın.
start_url
start_url
zorunlu bir özelliktir. Bu, tarayıcıya uygulamanızın başlatılacağı yeri bildirir ve kullanıcının uygulamanızı ana ekranına eklerken uygulamanın hangi sayfada bulunduğuna bakmasını engeller.
start_url
, kullanıcıyı bir ürün açılış sayfasına değil, doğrudan uygulamanıza yönlendirmelidir. Kullanıcıların uygulamanızı açtıktan hemen
sonra ne yapmak isteyeceğini düşünün ve onları oraya yerleştirin.
background_color
background_color
özelliği, uygulama mobil cihazlarda ilk kez başlatıldığında başlangıç ekranında kullanılır.
display
Uygulamanız başlatıldığında hangi tarayıcı kullanıcı arayüzünün gösterileceğini özelleştirebilirsiniz. Örneğin, adres çubuğu ve tarayıcı kullanıcı arayüzü öğelerini gizleyebilirsiniz. Oyunları tam ekranda
başlayacak şekilde bile hazırlayabilirsiniz. display
özelliği aşağıdaki değerlerden birini alır:
Özellik | Davranış |
---|---|
fullscreen |
Web uygulamasını herhangi bir tarayıcı kullanıcı arayüzü olmadan açar ve kullanılabilir görüntüleme alanının tamamını kaplar. |
standalone |
Web uygulamasını, bağımsız bir uygulama gibi görünecek ve hissettirecek şekilde açar. Uygulama, tarayıcıdan ayrı olarak kendi penceresinde çalışır ve adres çubuğu gibi standart tarayıcı kullanıcı arayüzü öğelerini gizler. |
minimal-ui |
Bu mod, standalone moduna benzer ancak gezinmeyi kontrol etmek için kullanıcıya geri ve yeniden yükle düğmeleri gibi minimum sayıda kullanıcı arayüzü öğesi sağlar.
|
browser |
Standart bir tarayıcı deneyimi. |
display_override
Web uygulamanızın nasıl görüntüleneceğini seçmek için manifest dosyasında daha önce açıklandığı gibi bir display
modu ayarlayın. Tarayıcıların tüm görüntüleme modlarını desteklemeleri gerekmez ancak özellik tanımlı yedek zincirini ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
) desteklemeleri gerekir. Belirli bir modu desteklemedikleri takdirde zincirdeki bir sonraki görüntüleme moduna geçerler. Nadir durumlarda bu yedekler sorunlara neden olabilir. Örneğin, bir geliştirici "minimal-ui"
desteklenmediğinde "browser"
görüntüleme moduna geri dönmeye zorlanmadan "minimal-ui"
isteğinde bulunamaz. Ayrıca mevcut davranış, yedek zincirinde yerleri olmadığı için yeni görüntüleme modlarının geriye dönük uyumlu olarak kullanıma sunulmasını da imkansız hale getiriyor.
Tarayıcının display
özelliğinden önce dikkate aldığı display_override
özelliğini kullanarak kendi yedek sıranızı ayarlayabilirsiniz. Değeri, listelenen sırada dikkate alınan bir dize dizisidir ve ilk desteklenen görüntüleme modu uygulanır. Bunların hiçbiri desteklenmiyorsa tarayıcı display
alanını değerlendirmeye devam eder. display
alanı yoksa tarayıcı display_override
alanını yoksayar.
Aşağıda display_override
öğesinin nasıl kullanılacağıyla ilgili bir örnek verilmiştir. "window-control-overlay"
ile ilgili ayrıntılar bu sayfada kapsam dışındadır.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Tarayıcı, bu uygulamayı yüklerken önce "window-control-overlay"
kullanmayı dener. Bu mevcut değilse "minimal-ui"
değerine ve ardından display
özelliğinden "standalone"
değerine geri döner. Bunların hiçbiri mevcut değilse tarayıcı standart yedek zincirine döner.
scope
Uygulamanızın scope
öğesi, tarayıcının uygulamanızın bir parçası olarak kabul ettiği URL'ler kümesidir. scope
, uygulamaya giden tüm giriş ve çıkış noktalarını içeren URL yapısını kontrol eder ve tarayıcı, kullanıcının uygulamadan ne zaman ayrıldığını belirlemek için bunu kullanır.
scope
ile ilgili birkaç not daha:
- Manifest'inize bir
scope
eklemezseniz varsayılan olarak ima edilenscope
başlangıç URL'si olur ancak dosya adı, sorgusu ve parçası kaldırılır. scope
özelliği, web uygulamanızdaki gezinme kapsamının artırılmasını sağlayacak göreli bir yol (../
) veya daha üst düzey bir yol (/
) olabilir.start_url
, kapsam içinde olmalıdır.start_url
,scope
özelliğinde tanımlanan yolla görelidir./
ile başlayan birstart_url
her zaman kaynağın kökü olur.
theme_color
theme_color
, araç çubuğunun rengini belirler ve uygulamanın görev değiştiricilerinde yapılan önizlemesine yansıtılabilir. theme_color
, dokümanınızın başlığında belirtilen meta
tema rengiyle eşleşmelidir.
Medya sorgularında theme_color
Bir medya sorgusundaki theme_color
değerini, meta
tema renk öğesinin media
özelliğini kullanarak ayarlayabilirsiniz. Örneğin, bu şekilde açık mod için bir renk,
koyu mod için başka bir renk tanımlayabilirsiniz. Ancak bu tercihleri manifest dosyanızda tanımlayamazsınız. Daha fazla bilgi için w3c/manifest#975 GitHub sorununu inceleyin.
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
shortcuts
mülkü, uygulamanızdaki temel görevlere hızlı erişim sağlayan bir uygulama kısayolu nesneleri dizisidir. Her üye, en az bir name
ve url
içeren bir sözlüktür.
description
description
özelliği, uygulamanızın amacını açıklar.
Chrome'da, tüm platformlarda maksimum açıklama uzunluğu 300 karakterdir. Açıklama bundan daha uzunsa tarayıcı, açıklamayı üç nokta karakteriyle kısaltır. Android'de, açıklamada da en fazla yedi satır metin olmalıdır.
screenshots
screenshots
özelliği, yaygın kullanım senaryolarında uygulamanızı temsil eden bir görüntü nesneleri dizisidir. Her nesne resmin src
, sizes
özelliği ve type
özelliğini içermelidir. form_factor
özelliği isteğe bağlıdır.
Yalnızca geniş ekranlarda geçerli ekran görüntüleri için "wide"
veya yalnızca dar ekran görüntüleri için "narrow"
olarak ayarlayabilirsiniz.
Chrome'da, görselin aşağıdaki ölçütleri karşılaması gerekir:
- Genişlik ve yükseklik en az 320 piksel, en fazla 3.840 piksel olmalıdır.
- Maksimum boyut, minimum boyut uzunluğunun 2,3 katından fazla olamaz.
- Uygun form faktörüyle eşleşen tüm ekran görüntüleri aynı en boy oranına sahip olmalıdır.
- Chrome 109 sürümünden itibaren masaüstünde yalnızca
form_factor
özelliği"wide"
olarak ayarlanmış ekran görüntüleri gösterilir.
- Chrome 109 sürümünden itibaren masaüstünde yalnızca
- Chrome 109'da,
form_factor
değeri"wide"
olarak ayarlanmış ekran görüntüleri Android'de yoksayılır.form_factor
içermeyen ekran görüntüleri, geriye dönük uyumluluk için gösterilmeye devam etmektedir.
Masaüstünde Chrome, bu ölçütleri karşılayan en az bir, en fazla sekiz ekran görüntüsü gösterir. Diğerleri yoksayılır.
Android üzerinde Chrome, bu ölçütleri karşılayan en az bir, en fazla beş ekran görüntüsü görüntüler. Diğerleri yoksayılır.
Web uygulaması manifestini sayfalarınıza ekleyin
Manifest'i oluşturduktan sonra, Progresif Web Uygulamanızın tüm sayfalarına bir <link>
etiketi ekleyin. Örneğin:
<link rel="manifest" href="/manifest.json">
Manifest dosyanızı test etme
Manifest'inizin düzgün şekilde ayarlandığını doğrulamak için Chrome Geliştirici Araçları'nın Uygulama panelindeki Manifest bölmesini kullanın.
Bu bölme, manifest özelliklerinizin birçoğunun kullanıcılar tarafından okunabilir bir sürümünü sağlar ve tüm resimlerin düzgün şekilde yüklendiğini doğrulamanıza olanak tanır.
Mobil cihazda başlangıç ekranları
Uygulamanız mobil cihazlarda ilk kez başlatıldığında tarayıcının başlaması ve ilk içeriğin oluşturulmaya başlaması biraz zaman alabilir. Tarayıcı, uygulamanın çalışmadığını düşünmesine neden olabilecek beyaz bir ekran yerine ilk boyamaya kadar bir başlangıç ekranı gösterir.
Chrome, başlangıç ekranını manifest dosyanızda belirtilen name
, background_color
ve icons
kodlarından otomatik olarak oluşturur. Başlangıç ekranından uygulamaya sorunsuz bir geçiş oluşturmak için yükleme sayfası ile aynı renkte background_color
yapın.
Chrome, başlangıç ekranları için cihaz çözünürlüğüne en yakın simgeyi seçer. Çoğu durum için 192 piksel ve 512 piksellik simgeler yeterli olsa da daha iyi bir eşleşme için ek simgeler de sağlayabilirsiniz.
Daha fazla bilgi
Web uygulaması manifest dosyanıza ekleyebileceğiniz diğer mülkler hakkında bilgi edinmek için MDN Web App Manifest dokümanlarına bakın.