Web uygulaması manifest dosyası ekle

Tarayıcı Desteği

  • 39
  • 79
  • x
  • x

Kaynak

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.
Bağımsız görüntülü reklam içeren PWA penceresi örneği.
Bağımsız kullanıcı arayüzü.
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.
Minimal kullanıcı arayüzü görüntüsüne sahip PWA penceresi örneği.
Minimal kullanıcı arayüzü.
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 edilen scope 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 bir start_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.

Özel theme_color özelliğine sahip bir PWA penceresi örneği.
Özel theme_color içeren PWA penceresi örneği.

Medya sorgularında theme_color

Tarayıcı Desteği

  • 93
  • 93
  • 106
  • 15

Kaynak

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'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.

Masaüstü ve mobil cihazlarda daha zengin kullanıcı arayüzünün ekran görüntüleri.
Masaüstü ve mobil cihazlarda daha zengin yükleme kullanıcı arayüzü.

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.

Chrome Geliştirici Araçları&#39;nda, manifest sekmesinin seçili olduğu uygulama paneli.
Manifest dosyanızı Geliştirici Araçları'nda test edin.

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.