Web App: Manifest
Progressive Web App (PWA) yazısı ve örnek uygulaması öncesinde, Single Page Application (SPA) ve ardından Service Workers ile başlayan yazı akışına Manifest ile devam ediyoruz. Bu sayede, PWA örneğini oluşturmaya başladığımızda kullanabileceğimiz tüm araçlara dair ön bir bilgi sağlamayı amaçlıyorum.
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 Manifest1 ve W3C > Web App Manifest2 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 Generator3 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 NPM4 ve YARN5 eklenti detay sayfalarını inceleyebilirsiniz.
Oluşturulan bir manifest içeriğini Chrome DevTools > Application ile doğrulayabilirsiniz6.
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.