Web App: Manifest

Web App Manifest

Web App Manifest, internet tarayıcılarına web uygulaması hakkında bilgi veren bir JSON dosyasıdır. En temel haliyle bu bilgiler site adı (name), açıklama (description) ve simge (icon)’den oluşmaktadır. Ancak, amaca göre ve belirli kurallar çerçevesinde daha da detaylandırılabilir. Aşağıda, manifest tanımlama bölümünde oluşturulmuş alternatif uygulama manifestolarını görebilirsiniz.

Manifest Kullanımı

Tanım bölümünde de belirttiğim üzere manifest bir JSON dosyasıdır, bu sebeple yazımında JSON yazım kuralları geçerlidir. Oluşturulan manifest genel olarak manifest.json şeklinde isimlendirilir. Ancak, bu bir zorunluluk değildir. Çünkü, tanımlanan manifest dosyası <head>...</head> arasına yerleştireceğimiz bir link etiketiyle tarayıcıya iletilir.

<link rel="manifest" href="./manifest.json" />

Manifest tanımı herhangi bir kimlik bilgisi (credentials) olmadan yapılır (aynı etki alanında olsa bile). Ancak, bildirim için kimlik bilgisi gerekiyorsa, bildirim etiketine crossorigin = "use-credential" eklenebilir.

Manifest Tanımlama

Hızlı bir şekilde örneklendirme aşamasına geçelim. Aşağıda, ihtiyaçlarınıza göre kullanabileceğiniz örnekler iletiyorum. Örnekler sonrasında, ilgili alanlarla ilgili ayrıca notlara yer verdim. Bu bilgilere dikkat ederek örnekleri kendi web uygulamanıza göre düzenleyebilirsiniz.

{
  "name": "Web Uygulamasının Adı",
  "description": "Web uygulamasının açıklaması",
  "icons": [{
    "src": "images/icon.png",
    "sizes": "192x192"
  }]
}

Yukarıdaki basit örnek bir web uygulaması için en temel bilgileri ifade etmektedir. İlgili icon tanımı ile uygulama akıllı telefon ve/veya tablete indirildiğinde belirtilen icon ile gösterilecektir. Şimdi, bu örneği biraz daha detaylandıralım.

{
  "lang": "en", // Uygulamanın dili
  "dir": "ltr", // Dil yazma sistemi / Direction
  "name": "Web Uygulamasının Adı",
  "description": "Web uygulamasının açıklaması",
  "short_name": "Uygulamanın Kısa Adı",
  "icons": [{
    "src": "icon/lowres.webp", // Webp formatlı düşük çözünürlüklü icon
    "sizes": "64x64",
    "type": "image/webp"
  },{
    "src": "icon/lowres.png",  // Png formatlı düşük çözünürlüklü icon
    "sizes": "64x64"
  }, {
    "src": "icon/hd_hi",  // Yüksek çözünürlüklü icon
    "sizes": "128x128"
  }],
  "scope": "/pages/", // Uygulamanın kapsam alanı
  "start_url": "/page/first.html", // Uygulamanın başlangıç sayfası (?source=pwa ve/veya ?utm_source=pwa gibi bir tanımla kaynak olarak işaretleme gerçekleştirilebilir)
  "display": "fullscreen", // Uygulamanın nasıl görüntüleneceği (fullscreen veya standalone)
  "orientation": "landscape", // Uygulamanın nasıl pozisyonlandırılacağı (portrait; dikey, landscape; yatay)
  "theme_color": "aliceblue", // Uygulamanın bar rengi
  "background_color": "red", // Uygulamanın arka plan görüntüleneceği
  "serviceworker": { // Service worker tanımı
    "src": "sw.js", // Service worker dosyası
    "scope": "/racer/", // Service worker işleminin uygulanacağı alan
    "update_via_cache": "none" // Önbellekleme işlemi
  },
  "screenshots": [{
    "src": "screenshots/in-app-1x.jpg", // Uygulamanın ekran görüntüsü
    "sizes": "640x480",
    "type": "image/jpeg"
  },{
    "src": "screenshots/in-app-2x.jpg", // Uygulamanın ekran görüntüsü
    "sizes": "1280x920",
    "type": "image/jpeg"
  }]
}

Yukarıdaki örnek tipik bir manifest tanımı olarak nitelendirilebilir. Bir PWA için gerekli olan tüm bilgiler bu manifesto içerisinde tanımlanmıştır. Uygulama adı (name) uygulama açılırken (app install prompt) görüntülecek isim iken uygulamanın kısa adı (short_name) uygulama ana ekrana eklendiğinde (Add to Home Screen), launcher ve diğer karakter kısıtlaması olan bölümlerde görüntülenecek adı ifade etmektedir.

Chrome internet tarayıcısı için 192×192 pixel ve 512×512 pixel icon tanımları yeterlidir. Bu çözünürlükler dışında gereksinimler için, Chrome cihazlara göre icon’ları otomatik olarak boyutlandırabilmektedir.

Arka plan rengi (background_color), uygulama ilk çalıştırıldığında (splash screen) kullanılır.

Display tanımı fullscreen, standalone, minimal-ui ve browser ifadelerinden birini alır. Fullscreen ile uygulama herhangi bir tarayıcı UI elemanı olmaksızın açılır ve tüm görüntü alanını kullanabilir. Standalone ile web uygulaması sanki bir bağımsız uygulama gibi görüntülenir. Uygulama kendi penceresinde ve tarayıcıdan ve tarayıcıya ait UI elemanlarından bağımsız sunulur. Minimal-ui, fullscreen’e benzer bir özelliktedir. Ancak, minimal düzeyde de olsa back-forward, reload gibi tarayıcıya ait UI elemanları içerir. Browser ise uygulamanın standart browser UI yapısında sunulmasını sağlar.

Scope, uygulamanın nerede başladığını ve nerede bittiğini (entry ve exit points) ifade eder. Performans ve kullanıcı deneyimi için önemli bir tanımdır. start_url tanımı da scope çerçevesi içerisinde yer almalıdır. Ek olarak, eğer kullanıcı scope çerçevesi dışında kalan bir bağlantıyı tıklarsa bağlantı var olan PWA penceresi içerisinde görüntülenir. Ancak, bağlantının PWA çerçevesi dışında, bir tarayıcı sekmesi (tab) olarak açılması isteniyorsa bağlantıya (...) target tanımı yapılmalıdır; target="_blank".

<a href="" target="_blank" rel="noopener noreferrer">...</a>

Ayrıca, kullanılabilecek diğer tanımlar ve tarayıcı desteği ile ilgili olarak MDN Web Docs > Web App Manifest¹ ve W3C > Web App Manifest² sayfalarını takip edebilirsiniz. Bir kaç ek not daha.

Eğer bir scope tanımı yapılmamışsa, scope ön tanımlı olarak web app manifest dosyasının bulunduğu dizin olarak ele alınır.
Scope tanımı bir relative path (../) ya da uygulamanın navigasyon kapsamının artmasına izin verecek herhangi bir üst path (/) ile yapılabilir.

Manifest Oluşturma ve Doğrulama

Örnek manifest tanımlarının düzenlenerek kullanılabileceğinden bahsetmiştim. Ancak, farklı araçlar da elbette bu süreçte değerlendirilebilir. Örneğin, Web App Manifest Generator³ uygulaması ile kolaylıkla ve geçerli tanımlamalar yapabilirsiniz. Diğer yandan, webpack ile kullanabileceğiniz webpack-pwa-manifest eklentisi ile manifest işlemlerini otomatik bir şekilde de ele alabilirsiniz. Bunun için NPM veya YARN ile ilgili paketi indirebilirsiniz.

npm install --save-dev webpack-pwa-manifest
# ya da
yarn add --save-dev webpack-pwa-manifest

Ardından, ilgili eklentiyi webpack.config.js dosyasına şu şekilde işleyebiliriz:

// ES6+
import WebpackPwaManifest from 'webpack-pwa-manifest'

// ES5
var WebpackPwaManifest = require('webpack-pwa-manifest')
//...
plugins: [
  new WebpackPwaManifest({
    name: 'Web Uygulamasının Adı',
    short_name: 'Uygulamanın Kısa Adı',
    description: 'Web uygulamasının açıklaması',
    background_color: '#ffffff',
    crossorigin: 'use-credentials', // null, use-credentials ya da anonymous olabilir
    icons: [
      {
        src: path.resolve('src/assets/icon.png'),
        sizes: [96, 128, 192, 256, 384, 512] // çoklu boyut
      },
      {
        src: path.resolve('src/assets/large-icon.png'),
        size: '1024x1024' // teknik özellikler de kullanılabilir
      }
    ]
  })
]

Eklentiye dair daha detaylı bilgi için NPM⁴ ve YARN⁵ eklenti detay sayfalarını inceleyebilirsiniz.

Oluşturulan bir manifest içeriğini Chrome DevTools > Application ile doğrulayabilirsiniz⁶.

Son Olarak

Manifest tanımının ardından tarayıcı web uygulaması hakkında bilgi sahibi olacak ve buna uygun olarak davranışlar sergileyecektir. Örneğin, Home Screen bildirimi de manifest dosyasıyla ilişkili olarak eyleme geçmektedir. Aşağıda, paylaştığım bilgilere ek olarak değerlendirilebilecek farklı yazıları da aktarıyorum.